Skip to content

normalize_to_region

Divide the flux by its NaN-safe mean over [wave_lo, wave_hi].
Category Continuum
Backend numpy - implemented here on top of numpy primitives
Version 3.1.0
Reads ctx.spectrum (a Spectrum1D)
Writes spectrum, metrics.region_mean, metrics.applied, metrics.region_snr

out = flux / nanmean(flux[wave_lo:wave_hi]). The window is closed at both ends and clamped to the spectrum's wavelength range. v2.0.0 — uncertainty (rule in place since 1.0.0, now documented ; no numerical change) : σ_out = σ_in / |region_mean| — the region mean is treated as noise-free (its standard error, σ/√N over the window, is not propagated). If the region mean is zero or non-finite the algorithm fails with a clear message rather than emitting NaN. v3.0.0: masked samples (Spectrum1D.mask) are ignored by the region mean and n_samples counts the usable samples ; the output keeps their flux, divided like every other sample, and carries the mask through. v3.1.0 — window_selection: 'nearest' (default, the nearest-sample indices of wave_lo and wave_hi) or 'within' (every sample with wave_lo ≤ λ ≤ wave_hi ; fewer than 3 usable samples is a configuration error and fails). Significance guard, active when min_snr > 0 or on_invalid = 'skip': mean and standard error of the mean (std with ddof = 1 over √n) of the usable window samples, S/N = mean / sem (±1e6 when sem = 0) ; the window is invalid when mean ≤ 0 or S/N < min_snr, and then on_invalid decides: 'fail' (default) fails, 'skip' succeeds with applied = 0, region_mean, region_snr, wave_lo, wave_hi, n_samples and the spectrum untouched. A valid window is divided exactly as before ; with the guard active the metrics gain applied = 1 and region_snr. With the defaults the brick is byte-identical to 3.0.0, metrics included.

Parameters

Parameter Default Required Description
wave_lo 0.0 yes Lower bound of the reference window (same unit as the wavelength axis).
wave_hi 0.0 yes Upper bound of the reference window.
window_selection 'nearest' - 'nearest': the samples between the nearest-sample indices of wave_lo and wave_hi (default) ; 'within': the samples with wave_lo ≤ λ ≤ wave_hi.
min_snr 0.0 - Guard: the window mean must be positive and at least this many standard errors above zero. 0 disables the significance test (the sign test still runs when on_invalid is 'skip').
on_invalid 'fail' - 'fail' (default) or 'skip' when the guard rejects the window: skip leaves the spectrum untouched and reports applied = 0.

Use it

from spectro_kernel import run_algorithm

output = run_algorithm("normalize_to_region", ctx, {
    "wave_lo": 0.0,
    "wave_hi": 0.0,
    "window_selection": "nearest",
    "min_snr": 0.0,
    "on_invalid": "fail"
})

spectro run normalize_to_region --input spectrum.fits \
  --param wave_lo=0.0 \
  --param wave_hi=0.0 \
  --param window_selection=nearest \
  --param min_snr=0.0 \
  --param on_invalid=fail

{
  "tool": "normalize_to_region",
  "arguments": {
    "session_id": "<session_id>",
    "params": {
      "wave_lo": 0.0,
      "wave_hi": 0.0,
      "window_selection": "nearest",
      "min_snr": 0.0,
      "on_invalid": "fail"
    }
  }
}

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

References

  • Tody 1986, Proc. SPIE 627, 733 — IRAF continuum heritage.
  • Bevington & Robinson 2003, Data Reduction and Error Analysis for the Physical Sciences, 3rd ed., McGraw-Hill — §4.2, standard error of the mean (the significance statistic of the guard).
  • compare_normalisations - Run every continuum-normalisation method on ctx.spectrum and collect them.
  • normalize_edges - Normalise a spectrum using a continuum fitted only on its line-free edges.
  • normalize_max - Normalise a spectrum by dividing the flux by its maximum value.
  • normalize_percentile - Normalise a spectrum by dividing the flux by a high percentile of itself.
  • normalize_polynomial - Normalise the continuum to unity with a sigma-clipped polynomial fit.
  • normalize_spline - Normalise the continuum with an IRAF-style iteratively clipped cubic spline.
  • subtract_continuum - Subtract a sigma-clipped polynomial continuum, leaving the line residual.