Skip to content

stack_spectra

Combine every spectrum in ctx.spectra into one stacked spectrum.
Category Stacking
Backend numpy - implemented here on top of numpy primitives
Version 2.1.0
Reads ctx.spectra (a list of Spectrum1D)
Writes spectrum, metrics.n_stacked, metrics.n_nan_samples

Median stacking is the most robust against cosmic rays and outliers; mean maximises SNR for clean data; sum is useful for co-adding sub-exposures. Each spectrum contributes only inside its own wavelength range: samples of the reference grid outside a spectrum's coverage are NaN for that spectrum and ignored by the NaN-aware combiners (a sample covered by no spectrum at all is NaN in the output; count in metrics.n_nan_samples). v2.0.0: v1 let numpy.interp clamp to the edge value, so a spectrum was extrapolated as a constant over the whole grid — with s1 = 1.0 on 4000-5000 Å and s2 = 3.0 on 4500-5500 Å the v1 mean at 4000 Å was 2.0; it is now 1.0 (2.0 inside the overlap). v2.1.0 adds method='weighted' (mean, median and sum are untouched): the Bevington & Robinson weighted mean Σ w S / Σ w, sample by sample, with the stack uncertainty (Σ w)^(−1/2) written to ctx.spectrum.uncertainty. Weights, in order of precedence: the 'weights' parameter (one positive number per spectrum, interpreted as inverse variances 1/σ_i² — the output uncertainty is only meaningful on that scale); else, when every spectrum carries an uncertainty array, per-sample inverse variances w_ij = 1/σ_ij² (interpolated onto the grid like the flux; non-finite or zero σ excludes that sample); else per-spectrum w_i = DER_SNR_i² (Stoehr et al. 2008) — for continuum-normalised spectra this is 1/σ_i² in continuum units, otherwise the output uncertainty is relative to the median flux. The weighting actually used is recorded in ctx.spectrum.meta ('weighting', 'weights').

Parameters

Parameter Default Required Description
method 'median' - Combination method: one of ['mean', 'median', 'sum', 'weighted'].
reference_index 0 - Index in ctx.spectra whose wavelength grid is the target.
weights None - method='weighted' only: list of one positive weight per spectrum (inverse variances); null = from the uncertainty arrays, else DER_SNR².

Use it

from spectro_kernel import run_algorithm

output = run_algorithm("stack_spectra", ctx, {
    "method": "median",
    "reference_index": 0,
    "weights": None
})

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

{
  "tool": "stack_spectra",
  "arguments": {
    "session_id": "<session_id>",
    "params": {
      "method": "median",
      "reference_index": 0,
      "weights": null
    }
  }
}

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

References

  • Tody 1993, ASP Conf. Ser. 52, 173 — IRAF scombine: spectra interpolated to a common dispersion, then summed / averaged / medianed sample by sample (weighted combination via its 'weight' parameter).
  • Bevington & Robinson 2003, Data Reduction and Error Analysis for the Physical Sciences, 3rd ed., ch. 4 — weighted mean μ = Σ w_i x_i / Σ w_i with w_i = 1/σ_i² and its uncertainty σ_μ = (Σ w_i)^(−1/2).