Skip to content

extract_spectrum_boxcar

Trace (easyspec) + pure-numpy aperture extraction on ctx.image.
Category Extraction (2-D to 1-D)
Backend easyspec - wraps the EasySpec reduction library (optional extra reduction)
Version 2.0.0
Reads ctx.image (an ImageFrame)
Writes spectrum, metrics.boxcar_columns_without_sky

Tracing uses easyspec.tracing (argmax → polynomial). Extraction is a numpy aperture sum over ±trace_half_width around the per-column trace position, fully edge-safe (any partial slice outside the detector contributes zero). tophat ⇒ standard boxcar; gaussian ⇒ profile-weighted (Gaussian fit on the mean column profile). easyspec is imported lazily inside run(). Note: the gaussian mode here is profile-weighted but NOT variance-weighted and does NOT propagate per-pixel uncertainty or reject cosmics during extraction. For the full Horne 1986 estimator (inverse-variance weighting, empirical profile, iterative cosmic rejection, uncertainty propagation) see extract_spectrum_optimal — choose it for faint, read-noise-limited sources or when downstream code needs Spectrum1D.uncertainty. Sky geometry: with shift_y_pixels > 0 the two flanking windows run from the aperture edge (trace ± trace_half_width) out to median_trace ± shift_y_pixels, so each is about shift_y_pixels − trace_half_width rows high; shift_y_pixels must exceed trace_half_width (refused otherwise). v2.0.0: the per-column sky is the mean of the NON-empty windows — v1 averaged a 0 in for an empty window, so a tilted trace (which empties one window over many columns because the bounds follow the median trace) had its sky halved there (audit case: 162/400 columns at half sky). Columns where both windows are empty get sky = 0 and are counted in the additive metric boxcar_columns_without_sky. The pixel axis is 0-based (numpy.arange(npix)).

Parameters

Parameter Default Required Description
trace_method 'argmax' - easyspec trace method: 'argmax', 'moments' or 'multi'.
trace_poly_order 2 - Polynomial order of the trace fit.
trace_y_pixel_range 15 - Half-window (rows) for the trace search.
trace_peak_height 100.0 - Minimum peak height when locating the trace.
trace_peak_distance 50 - Minimum separation between traces (multi mode).
trace_half_width 7 - Aperture half-width (rows) for both trace and extraction.
extraction_weights 'tophat' - 'tophat' (boxcar sum) or 'gaussian' (Horne-weighted).
shift_y_pixels 0 - Half-height (rows) of the sky region centred on the median trace row: each flanking sky window spans from the aperture edge (trace ± trace_half_width) out to median_trace ± shift_y_pixels, i.e. ~ shift_y_pixels - trace_half_width rows. Must exceed trace_half_width; 0 disables background subtraction.

Use it

from spectro_kernel import run_algorithm

output = run_algorithm("extract_spectrum_boxcar", ctx, {
    "trace_method": "argmax",
    "trace_poly_order": 2,
    "trace_y_pixel_range": 15,
    "trace_peak_height": 100.0,
    "trace_peak_distance": 50,
    "trace_half_width": 7,
    "extraction_weights": "tophat",
    "shift_y_pixels": 0
})

The CLI loads a single 1-D spectrum with --input; this algorithm needs ctx.image (an ImageFrame). Run it from Python or as a step of a pipeline preset.

{
  "tool": "extract_spectrum_boxcar",
  "arguments": {
    "session_id": "<session_id>",
    "params": {
      "trace_method": "argmax",
      "trace_poly_order": 2,
      "trace_y_pixel_range": 15,
      "trace_peak_height": 100.0,
      "trace_peak_distance": 50,
      "trace_half_width": 7,
      "extraction_weights": "tophat",
      "shift_y_pixels": 0
    }
  }
}

Every algorithm is an MCP tool of the same name; describe_algorithm returns this page's metadata as JSON.

References

  • Horne 1986, PASP 98, 609 — optimal aperture extraction (tophat is the standard unweighted variant).
  • Tody 1986, Proc. SPIE 627, 733 — IRAF apall / aptrace heritage.
  • easyspec.extraction.extraction.tracing — argmax / moments trace fit.