spectro-kernel 0.8.0__tar.gz → 0.9.0__tar.gz

{spectro_kernel-0.8.0 → spectro_kernel-0.9.0}/CHANGELOG.md

@@ -6,6 +6,133 @@ Until `1.0.0` the public API may change between minor versions.
 
 ## [Unreleased]
 
+## [0.9.0] — 2026-10-23
+
+Bricks for self-calibrating long-slit instruments, requested by NORVIS Redux,
+which reduces auroral long-slit spectra with ten local bricks that implement
+generic, published methods. Five new bricks and five extensions ; every
+extension keeps its default behaviour **byte-identical to 0.8.1, metrics
+included** (MINOR attribute bumps, no MAJOR). Each brick was checked bit for
+bit against the Redux reference implementation on a synthetic harness covering
+the apply, skip and failure branches (report in the pull request). No NORVIS
+constant became a default : which lines, which header keyword, which geometry
+are required parameters.
+
+### Added
+
+- **`refine_wavelength_zeropoint`** (wavelength_calibration, 1.0.0, scipy) — a
+  guarded pure zero-point shift of a calibrated axis from one emission line of
+  the spectrum itself (Osterbrock, Fulbright, Martel, Keane, Trager & Basri
+  1996, PASP 108, 277 ; Osterbrock, Fulbright & Bida 1997, PASP 109, 614 :
+  night-sky lines as wavelength standards). Gaussian on a linear baseline
+  inside `reference_wavelength ± search_halfwidth_angstrom`, Δλ = λ_ref − λ_fit
+  added to the whole axis, dispersion untouched. Skips (`applied = 0`, measured
+  centre, shift and S/N reported) on a faint line (`min_snr`), a centre outside
+  the window or a shift beyond `max_shift_angstrom` ; fails on a pixel axis.
+  `reference_wavelength` is required.
+- **`measure_line_offsets`** (quality, 1.0.0, scipy) — where known lines land on
+  a calibrated axis, measured and never applied : per line
+  `line_<λ>_detected`, `line_<λ>_snr`, `line_<λ>_offset_angstrom`, plus
+  `n_lines_detected` and `mean_offset_angstrom`. Same fit helper as the
+  zero-point brick (`wavelength_calibration/_line_fit.py`).
+  `reference_wavelengths` is required.
+- **`flat_normalize_response`** (preprocessing, 1.0.0, scipy) — the IRAF
+  `response` recipe (Massey, Valdes & Barnes 1992 ; Howell 2006 ch. 4) : the
+  flat over its own smoothed lamp spectrum, scaled to median 1 over the lit
+  area, applied only where the lamp gave signal and the response lies within
+  `[min_response, max_response]`. `pedestal_mode = "dark_margin"` holds the
+  science pedestal out of the division, `(image − p) / N + p`. Metrics : lit
+  span, lit rows, corrected fraction, pixel-response scatter, illumination
+  percentiles. Fills the gap the `flat_normalize` docstring declared.
+- **`correct_smile_xcorr`** (preprocessing, 1.0.0, astropy) — line curvature
+  measured on the frame itself (Kelson 2003, PASP 115, 688 ; Massey, Valdes &
+  Barnes 1992 ; Tonry & Davis 1979) : row bands cross-correlated against the
+  band at `reference_row` with parabolic sub-pixel refinement, shift(row)
+  fitted with an astropy `Polynomial1D` under two 3σ clipping passes,
+  re-anchored so the reference row is untouched and held constant outside the
+  fitted rows, every row resampled. Skips on a narrow lit span, a reference row
+  outside the lit rows, fewer than `min_bands` bands, a fit rms above
+  `max_fit_rms_px` or an amplitude above `max_amplitude_px`. Fit written to
+  `ctx.extras[output_key]`.
+- **`convert_flux_to_rayleigh`** (flux_calibration, 1.0.0, numpy) — a
+  response-corrected slit spectrum to rayleigh per nm (Hunten, Roach &
+  Chamberlain 1956, J. Atmos. Terr. Phys. 8, 345 ; Baker 1974, Appl. Opt. 13,
+  2160 ; Baker & Romick 1976, Appl. Opt. 15, 1966) through the solid angle
+  Ω = (w / f) · (N · p / (m · f)) and the absolute response scale read from the
+  response header under `response_scale_keyword` (required : the keyword is a
+  convention of whoever built the response). A `normalize_to_region` step is
+  undone. Missing scale or exposure time goes to `on_missing`.
+- `examples/longslit_selfcalibrated.py` — the ten bricks chained on a synthetic
+  frame, run by CI ; a section on self-calibrating long-slit instruments in the
+  library usage page.
+
+### Changed — extensions, defaults byte-identical to 0.8.1
+
+- `extract_spectrum_boxcar` 3.0.0 → 3.1.0 : `trace_method = "fixed"` extracts
+  the window `trace_center_row ± trace_half_width` on every column without
+  tracing (IRAF `apall` without `aptrace`), for extended sources that fill the
+  slit ; no easyspec or matplotlib import in that mode. Meta `trace_method` /
+  `trace_center_row` and metric `trace_center_row` in fixed mode only.
+- `wavelength_calibrate_polynomial` 1.0.1 → 1.1.0 : apply mode. `coefficients`
+  (`coefficients_order` lowest_first by default, or highest_first) and
+  `pixel_offset` evaluate a known dispersion solution instead of fitting one
+  (Massey & Hanson 2013, DOI 10.1007/978-94-007-5618-2_2) ; fails on a
+  non-increasing axis ; `required_params` is now empty, the pixel/wavelength
+  pairs are checked in `run()` when no coefficients are given. Metrics
+  `applied`, `wavelength_min_angstrom`, `wavelength_max_angstrom`,
+  `dispersion_angstrom_per_px` ; meta `wavelength_calibration = {method:
+  polynomial_coefficients, …}`.
+- `resample_linear` 2.0.0 → 2.1.0 : `oversampling`, the grid holds
+  `round((npix − 1) · oversampling) + 1` samples over the same bounds ;
+  exclusive with `step` and `n_points`.
+- `normalize_to_region` 3.0.0 → 3.1.0 : `window_selection` (`"nearest"`,
+  the default, or `"within"`) and a significance guard (`min_snr`,
+  `on_invalid`) on the standard error of the mean (Bevington & Robinson 2003) :
+  a negative mean, or one below `min_snr` standard errors, fails or skips
+  instead of inverting the spectrum or scaling it by noise.
+- `subtract_bias` 1.0.0 → 1.1.0 : the pedestal from an explicit
+  `overscan_columns` range or, with `overscan_auto`, from the columns the
+  spectrum never reaches (public `unilluminated_columns` : trimmed-mean column
+  profile, noise-based threshold, contiguous lit span widened by
+  `guard_columns`). Estimator : astropy sigma-clipped mean, which resolves the
+  level of a coarsely quantised integer frame below its step where a median
+  cannot ; residual reported. `min_columns` and `max_level_adu` go to
+  `on_invalid`. Precedence : `bias_level` > `overscan_columns` >
+  `overscan_auto` > master frame.
+- `tests/unit/test_uncertainty_propagation.py` pins the major version of
+  `resample_linear` instead of `2.0.0`, since the propagation rule of 2.0.0 is
+  kept by 2.1.0.
+
+## [0.8.1] — 2026-09-26
+
+One native brick, the last of the September audit's "trivial and already requested"
+gaps (item 1 of its catalogue table), plus the documentation hook for the published
+recipe collection. No existing brick changes its numbers.
+
+### Added
+
+- **`subtract_bias`** (preprocessing, 1.0.0, numpy) — the zero-level correction of
+  standard CCD reduction (Howell 2006, *Handbook of CCD Astronomy*, ch. 4 ; Massey
+  1997, *A User's Guide to CCD Reductions with IRAF*) : `science − master_bias` in
+  float64 on `ctx.image`, master frame read from `ctx.extras['master_bias']` as written
+  by `bias_combine`, or a constant `bias_level` (overscan mean) when no bias frames
+  exist. No exposure-time scaling (a bias carries no dark current). Negative pixels are
+  kept unless `clip_negative=True` ; metrics `bias_median`, `median_after`,
+  `n_negative`, `n_clipped`. Native counterpart of `subtract_bias_easyspec`, which
+  AuroreX asked for after the BZERO staging bug of the easyspec wrappers (fixed in
+  0.2.1) : the native path never stages a FITS file. Tests : exact recovery of a
+  synthetic truth under a gradient bias, integer-ADU input, constant level, precedence
+  of `bias_level` over the frame, clipping count, three failure paths, chaining after
+  `bias_combine`.
+- `subtract_bias_easyspec` 1.0.1 → 1.0.2 : `long_description` cross-references the
+  native brick (docstring only).
+
+### Documentation
+
+- The `docs` extra now installs `spectro-kernel-recipes>=0.2.0` (published on PyPI on
+  2026-09-26), so the online recipe catalogue lists the ten campaign recipes next to the
+  seven bundled ones. No runtime change.
+
 ## [0.8.0] — 2026-09-26
 
 The "exactness" release : the four method corrections the September audit

{spectro_kernel-0.8.0 → spectro_kernel-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: spectro-kernel
-Version: 0.8.0
+Version: 0.9.0
 Summary: A shared catalogue of astronomical spectroscopy algorithms, composable into reproducible pipelines, usable as a Python library, a CLI, or an MCP server.
 Project-URL: Homepage, https://github.com/matthieulel/spectro-kernel
 Project-URL: Documentation, https://docs.spectrokernel.io/
@@ -59,6 +59,7 @@ Requires-Dist: mkdocs-literate-nav>=0.6; extra == 'docs'
 Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
 Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
 Requires-Dist: pyyaml>=6.0; extra == 'docs'
+Requires-Dist: spectro-kernel-recipes>=0.2.0; extra == 'docs'
 Requires-Dist: zensical>=0.0.62; extra == 'docs'
 Provides-Extra: embedding-ml
 Requires-Dist: torch>=2.2; extra == 'embedding-ml'

{spectro_kernel-0.8.0 → spectro_kernel-0.9.0}/docs/usage/library.md

@@ -146,3 +146,32 @@ class MyMetric(BaseAlgorithm):
 Once the module is imported, `run_algorithm("my_metric", ctx)` works - and so does the
 CLI and the MCP server. The full walkthrough is in
 [Tutorial: add an algorithm](../tutorials/add-an-algorithm.md).
+
+## Self-calibrating long-slit instruments
+
+Some slit spectrographs calibrate themselves: no arc lamp, no bias frames, a
+dispersion solution stored in every frame. The catalogue covers that chain
+without a single instrument-specific brick:
+
+- `subtract_bias` with `overscan_auto` measures the pedestal on the columns the
+  spectrum never reaches (a sigma-clipped mean, which resolves a coarsely
+  quantised integer frame below its step);
+- `flat_normalize_response` divides by a flat normalised along the dispersion,
+  the IRAF `response` recipe, so the lamp spectrum is not imprinted;
+- `correct_smile_xcorr` measures the line curvature on the frame itself and
+  straightens it, anchored on the extraction row;
+- `extract_spectrum_boxcar` with `trace_method="fixed"` sums a fixed band of
+  rows, the right aperture for a source that fills the slit;
+- `wavelength_calibrate_polynomial` with `coefficients` applies the stored
+  dispersion polynomial, `resample_linear` with `oversampling` puts it on a
+  uniform grid, `refine_wavelength_zeropoint` takes the night's zero-point
+  drift out on a sky line and `measure_line_offsets` reports where the other
+  lines land without moving anything;
+- `normalize_to_region` with its significance guard, then
+  `convert_flux_to_rayleigh` for an absolute radiance in R/nm when the
+  response carries an absolute scale.
+
+Every one of these bricks skips rather than guesses when its input is doubtful
+(`applied = 0` in the metrics, context untouched). The chain runs end to end
+in [`examples/longslit_selfcalibrated.py`](https://github.com/matthieulel/spectro-kernel/blob/main/examples/longslit_selfcalibrated.py)
+on a synthetic frame.

spectro_kernel-0.9.0/examples/longslit_selfcalibrated.py

@@ -0,0 +1,59 @@
+"""Self-calibrating long-slit reduction: a synthetic sky frame to rayleigh per nm, no arc lamp.
+
+Run with ``python examples/longslit_selfcalibrated.py``: margin pedestal, response flat, smile
+measured on the frame, stored dispersion polynomial refined on [O I] 5577, R/nm. Deterministic.
+"""
+
+import numpy as np
+
+from spectro_kernel import WorkContext, run_algorithm
+from spectro_kernel.types import ImageFrame, Spectrum1D
+
+ROWS, COLS, PED, REF = 240, 600, 300.0, 120
+COEF = [5000.0, 2.5, -1.0e-4]  # stored solution lambda(column), lowest degree first
+LINES = (5577.34, 6300.30)  # [O I] night-sky lines (air)
+GEOM = {"slit_width_um": 20.0, "focal_mm": 50.0, "pixel_um": 2.9, "aperture_rows": 121}
+
+
+def synthetic(rng: np.random.Generator) -> tuple[ImageFrame, ImageFrame]:
+    cols, rows = np.arange(COLS, dtype=float), np.arange(ROWS, dtype=float)[:, None]
+    wave = np.polynomial.polynomial.polyval(cols, COEF) - 1.0  # 1 A zero-point drift
+    smile = 6.0 * ((rows - REF) / 100.0) ** 2  # line curvature, in columns
+    lit, slit = (cols >= 80) & (cols < 520), (rows >= 30) & (rows < 210)
+    centres = [np.interp(w, wave, cols) + smile for w in LINES]
+    sky = 30.0 * lit + sum(800.0 * np.exp(-0.5 * ((cols - c) / 2.0) ** 2) for c in centres)
+    lamp = 2000.0 * (1 + 0.4 * (cols - 80) / 440) * lit
+    pattern = 1.0 + 0.02 * rng.uniform(-1, 1, (ROWS, COLS))
+    noise = rng.normal(0, 2.0, (2, ROWS, COLS))
+    science = ImageFrame(pattern * slit * sky + PED + noise[0], header={"EXPTIME": 30.0})
+    return science, ImageFrame(pattern * slit * lamp + PED + noise[1], frame_type="flat")
+
+
+def main() -> None:
+    science, flat = synthetic(np.random.default_rng(0))
+    ctx = WorkContext(image=science, extras={"master_flat": flat})
+    ctx.extras["reference_spectrum"] = Spectrum1D(
+        [5000.0, 7000.0], [1, 1], header={"RESPABS": 2.5e8}
+    )
+    bias = run_algorithm("subtract_bias", ctx, {"overscan_auto": True})
+    print(f"subtract_bias: pedestal {bias.metrics['bias_median']:.1f} ADU from the unlit margin")
+    run_algorithm("flat_normalize_response", ctx, {"pedestal_mode": "dark_margin"})
+    run_algorithm("correct_smile_xcorr", ctx, {"reference_row": REF})
+    boxcar = {"trace_method": "fixed", "trace_center_row": REF, "trace_half_width": 60}
+    run_algorithm("extract_spectrum_boxcar", ctx, boxcar)
+    run_algorithm("wavelength_calibrate_polynomial", ctx, {"coefficients": COEF})
+    run_algorithm("resample_linear", ctx, {"oversampling": 2.0})
+    zp = run_algorithm("refine_wavelength_zeropoint", ctx, {"reference_wavelength": LINES[0]})
+    off = run_algorithm("measure_line_offsets", ctx, {"reference_wavelengths": list(LINES)})
+    delta, rest = zp.metrics["delta_angstrom"], off.metrics["line_6300_offset_angstrom"]
+    print(f"refine_wavelength_zeropoint: {delta:+.2f} A applied; [O I] 6300 now {rest:+.2f} A off")
+    window = {"wave_lo": 5800.0, "wave_hi": 5900.0, "window_selection": "within", "min_snr": 3.0}
+    run_algorithm("normalize_to_region", ctx, {**window, "on_invalid": "skip"})
+    ray = {**GEOM, "samples_per_pixel": 2.0, "response_scale_keyword": "RESPABS"}
+    out = run_algorithm("convert_flux_to_rayleigh", ctx, ray)
+    omega, unit = out.metrics["solid_angle_sr"], ctx.spectrum.flux_unit
+    print(f"convert_flux_to_rayleigh: solid angle {omega:.3e} sr, spectrum now in {unit}")
+
+
+if __name__ == "__main__":
+    main()

{spectro_kernel-0.8.0 → spectro_kernel-0.9.0}/pyproject.toml

@@ -70,6 +70,7 @@ docs = [
   "mkdocs-literate-nav>=0.6",     # fallback engine's nav plugin (Zensical has it built in)
   "jsonschema>=4.0",              # validates docs/ai/algorithms.json at build time
   "pyyaml>=6.0",
+  "spectro-kernel-recipes>=0.2.0", # the campaign collection, so the online catalogue lists its recipes
 ]
 all = [
   "spectro-kernel[catalogs,viz,storage,reduction,mcp,monitoring,embedding-wavelets,embedding-remote]",

spectro_kernel-0.9.0/src/spectro_kernel/algorithms/continuum/normalize_region.py

@@ -0,0 +1,210 @@
+"""Algorithm: normalise a spectrum by its mean flux over a chosen wavelength window."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+from ...base import AlgorithmOutput, BaseAlgorithm
+from ...errors import InvalidParameterError
+from ...registry import register_algorithm
+from ...types import AlgorithmCategory, WorkContext
+
+
+@register_algorithm(
+    "normalize_to_region",
+    category=AlgorithmCategory.CONTINUUM,
+    # 2.0.0: uncertainty rule (σ_out = σ_in / |region_mean|, in place since
+    # 1.0.0) documented in long_description. No numerical change.
+    # 3.0.0: masked samples (Spectrum1D.mask) are ignored by the region mean
+    # (n_samples counts the samples actually used) ; the output keeps their
+    # flux, divided like every other sample, and carries the mask through.
+    # 3.1.0: window_selection ("nearest" | "within"), significance guard
+    # (min_snr, on_invalid). Defaults byte-identical to 3.0.0, metrics included.
+    version="3.1.0",
+)
+class NormalizeToRegion(BaseAlgorithm):
+    """Divide the flux by its NaN-safe mean over ``[wave_lo, wave_hi]``.
+
+    The window should be a line-free continuum region so the output sits
+    near unity inside it. The companion of ``normalize_edges`` /
+    ``normalize_polynomial`` / ``normalize_max`` /
+    ``normalize_percentile`` with the explicit "normalise to *this*
+    band" convention — exactly what the IRAF ``continuum`` task does
+    when scaled by a measured band mean.
+
+    Two options, off by default, protect the division: ``window_selection =
+    "within"`` takes the samples inside ``[wave_lo, wave_hi]`` instead of the
+    nearest-sample indices, and a significance guard (``min_snr`` > 0 or
+    ``on_invalid = "skip"``) refuses to divide by a window mean that is
+    negative, or not at least ``min_snr`` standard errors above zero — a
+    negative level turns the spectrum upside down, a level lost in the noise
+    scales it by noise. Invalid windows then fail, or skip with ``applied = 0``
+    and the spectrum untouched.
+    """
+
+    backend = "numpy"
+    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).",
+    ]
+    long_description = (
+        "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."
+    )
+    default_params = {
+        "wave_lo": 0.0,
+        "wave_hi": 0.0,
+        "window_selection": "nearest",
+        "min_snr": 0.0,
+        "on_invalid": "fail",
+    }
+    required_params = ["wave_lo", "wave_hi"]
+    param_descriptions = {
+        "wave_lo": "Lower bound of the reference window (same unit as the wavelength axis).",
+        "wave_hi": "Upper bound of the reference window.",
+        "window_selection": (
+            "'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": (
+            "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' (default) or 'skip' when the guard rejects the window: skip "
+            "leaves the spectrum untouched and reports applied = 0."
+        ),
+    }
+    input_requirements = ["spectrum"]
+    output_produces = [
+        "spectrum",
+        "metrics.region_mean",
+        "metrics.applied",
+        "metrics.region_snr",
+    ]
+
+    def run(self, ctx: WorkContext, params: dict[str, Any]) -> AlgorithmOutput:
+        wave_lo = float(params["wave_lo"])
+        wave_hi = float(params["wave_hi"])
+        if wave_hi <= wave_lo:
+            raise InvalidParameterError("wave_hi must be strictly greater than wave_lo.")
+        spec = ctx.spectrum
+        if spec is None:
+            return AlgorithmOutput.fail("No ctx.spectrum to normalise.")
+
+        selection = str(params["window_selection"])
+        if selection not in ("nearest", "within"):
+            raise InvalidParameterError("window_selection must be 'nearest' or 'within'.")
+        on_invalid = str(params["on_invalid"])
+        if on_invalid not in ("fail", "skip"):
+            raise InvalidParameterError("on_invalid must be 'fail' or 'skip'.")
+        min_snr = float(params["min_snr"])
+        if min_snr < 0.0:
+            raise InvalidParameterError("min_snr must be >= 0.")
+        guard_active = min_snr > 0.0 or on_invalid == "skip"
+
+        wave = np.asarray(spec.wavelength, dtype=np.float64)
+        flux = np.asarray(spec.flux, dtype=np.float64)
+        if selection == "nearest":
+            # Nearest-sample window so users don't need to know the grid step.
+            lo_idx = int(np.argmin(np.abs(wave - wave_lo)))
+            hi_idx = int(np.argmin(np.abs(wave - wave_hi)))
+            lo_idx, hi_idx = sorted((lo_idx, hi_idx))
+            if hi_idx == lo_idx:
+                return AlgorithmOutput.fail(
+                    f"Reference window [{wave_lo}, {wave_hi}] is narrower than "
+                    "one sample of the spectrum's wavelength grid."
+                )
+            # Masked samples enter as NaN and are dropped with the non-finite ones.
+            region = spec.masked_flux()[lo_idx : hi_idx + 1]
+        else:
+            region = spec.masked_flux()[(wave >= wave_lo) & (wave <= wave_hi)]
+        region = region[np.isfinite(region)]
+        n_used = int(region.size)
+        if (selection == "within" or guard_active) and n_used < 3:
+            return AlgorithmOutput.fail(
+                f"Reference window [{wave_lo:g}, {wave_hi:g}] holds {n_used} usable "
+                "sample(s) — widen it."
+            )
+        region_mean = float(np.mean(region)) if n_used else float("nan")
+        region_snr: float | None = None
+        if guard_active:
+            sem = float(np.std(region, ddof=1) / np.sqrt(region.size))
+            if sem > 0:
+                region_snr = region_mean / sem
+            else:
+                region_snr = 1e6 if region_mean > 0 else -1e6
+            if region_mean <= 0.0 or region_snr < min_snr:
+                reason = (
+                    f"mean {region_mean:.4g} over [{wave_lo:g}, {wave_hi:g}] "
+                    f"(S/N {region_snr:.1f}) — dividing would "
+                    f"{'invert' if region_mean <= 0.0 else 'scale by noise'} the spectrum."
+                )
+                if on_invalid == "skip":
+                    return AlgorithmOutput.ok(
+                        metrics={
+                            "applied": 0.0,
+                            "region_mean": region_mean,
+                            "region_snr": float(region_snr),
+                            "wave_lo": wave_lo,
+                            "wave_hi": wave_hi,
+                            "n_samples": float(n_used),
+                        },
+                        message=f"Not normalised: {reason} Spectrum left untouched.",
+                    )
+                return AlgorithmOutput.fail(f"Reference window rejected: {reason}")
+        elif not np.isfinite(region_mean) or region_mean == 0.0:
+            return AlgorithmOutput.fail(
+                f"Reference region mean is {region_mean} — pick a window "
+                "with finite, unmasked, non-zero flux."
+            )
+
+        out = spec.with_flux(flux / region_mean, flux_unit="normalized")
+        if spec.uncertainty is not None:
+            out.uncertainty = spec.uncertainty / abs(region_mean)
+        out.meta["normalized_to_region"] = (wave_lo, wave_hi)
+        out.meta["normalization_factor"] = region_mean
+        ctx.spectrum = out
+
+        metrics: dict[str, float] = {
+            "region_mean": region_mean,
+            "wave_lo": wave_lo,
+            "wave_hi": wave_hi,
+            "n_samples": float(n_used),
+        }
+        if region_snr is not None:
+            metrics["applied"] = 1.0
+            metrics["region_snr"] = float(region_snr)
+        return AlgorithmOutput.ok(
+            metrics=metrics,
+            message=(
+                f"Normalised to mean {region_mean:.4g} over "
+                f"[{wave_lo:g}, {wave_hi:g}] ({n_used} samples)."
+            ),
+        )