spectro-kernel 0.2.0__tar.gz → 0.3.0__tar.gz

{spectro_kernel-0.2.0 → spectro_kernel-0.3.0}/CHANGELOG.md

@@ -6,6 +6,194 @@ Until `1.0.0` the public API may change between minor versions.
 
 ## [Unreleased]
 
+## [0.3.0] — 2026-06-09
+
+A focused expansion driven by the LineMill stellar-spectroscopy work
+(Alpy 600 / Star'Ex). **Seven new algorithms + one package data
+module**, all genuinely literature-based, none duplicating existing
+bricks. The minor-version bump signals a meaningful catalogue
+expansion (105 algorithms, up from 98), not an API break — every
+existing brick remains untouched.
+
+### Added — automatic wavelength calibration
+
+- **`lamp_atlas`** (package data, not an algorithm) — curated
+  persistent-line lists for `Ne`, `Ar`, `NeAr` and `ThAr` arc lamps,
+  sourced from the **NIST Atomic Spectra Database** (Kramida, Ralchenko,
+  Reader, NIST ASD Team). Embedded — no network at runtime. Sibling of
+  the existing ``lines.catalogs`` module. API: ``get_atlas(lamp,
+  wave_min=None, wave_max=None) -> ndarray`` of ``(wavelength_angstrom,
+  relative_intensity)``.
+- **`match_lamp_lines`** — automatic identification of arc-line peaks
+  against the bundled atlas. IRAF ``autoidentify`` heritage (Tody 1986
+  SPIE 627 733 ; Tody 1993 ASP Conf 52 173), with the robust ThAr-style
+  σ-clipped polynomial refinement (Murphy et al. 2007 MNRAS 378 221).
+  Writes ``ctx.extras["lamp_identifications"]`` in the exact shape
+  ``wavelength_calibrate_polynomial`` consumes — the old
+  hand-identified ``(pixel, λ)`` pairs become optional. Linear seed by
+  global anchor-pair brute-force (the local-greedy method's known
+  failure mode on Alpy 600 plein visible), then σ-clipped polyfit.
+
+### Added — native master-frame combiners
+
+- **`dark_combine`** and **`flat_combine`** — pure-numpy companions to
+  the existing native ``bias_combine``. Required by cloud workers that
+  source frames from S3 / R2 / memory queues, where the existing
+  ``*_easyspec`` variants (file round-trip) don't fit. Median (robust
+  default) or σ-clipped mean. ``dark_combine`` enforces uniform EXPTIME
+  by default (so the downstream ``dark_subtract(scale_by_exptime=True)``
+  has a well-defined factor). ``flat_combine`` produces the **raw**
+  master flat — the existing ``flat_normalize`` keeps the
+  normalisation responsibility. Howell 2006 ch. 4.
+
+### Added — flux calibration
+
+- **`response_from_standard`** — derive the instrumental response
+  curve from a standard-star observation. Observed/catalogue ratio,
+  Balmer + telluric masking, low-frequency spline (or polynomial) fit.
+  Output goes to ``ctx.extras["reference_spectrum"]`` so the existing
+  ``combine_spectra_arithmetic(operation="div")`` consumes it as the
+  "second spectrum" — same idiom as ``remove_telluric_division``.
+  References: Oke 1990 AJ 99 1621 ; Bessell 1999 PASP 111 1426 ; Hamuy
+  1992/1994 ; CALSPEC Bohlin et al. 2014 PASP 126 711 ; Hayes & Latham
+  1975 ApJ 197 593.
+
+### Added — optimal extraction (Horne 1986)
+
+- **`extract_spectrum_optimal`** — full Horne 1986 estimator: empirical
+  spatial profile (smoothed à la Marsh 1989), per-pixel variance model
+  ``V = signal/gain + RON²``, inverse-variance weighting, iterative
+  σ-clip cosmic-ray rejection, propagated 1-σ ``Spectrum1D.uncertainty``.
+
+  **This is NOT a replacement of ``extract_spectrum_boxcar``**. The
+  boxcar (with ``extraction_weights="gaussian"``) is a *profile-only*
+  estimator without variance model, cosmic rejection or uncertainty
+  propagation — it remains the right tool for high-SNR sources, wide
+  apertures, extended emission (aurora, nebulae). Pick
+  ``extract_spectrum_optimal`` when SNR matters most (faint, RN-limited
+  targets), when residual cosmics survive ``clip_cosmic_rays``, or
+  when downstream code needs ``Spectrum1D.uncertainty``. Cross-refs
+  added to both bricks' ``long_description`` to make the choice
+  explicit. References: Horne 1986 PASP 98 609 ; Marsh 1989 PASP 101
+  1032 ; Tody 1986 IRAF apall.
+
+### Added — automation bricks
+
+- **`detect_trace`** — pure-numpy trace detection that **exposes** the
+  trace as a product on ``ctx.extras["trace"] = {"center_row",
+  "poly_coef", "fwhm_px", "snr", "rms_px"}``. Today every
+  ``extract_spectrum_*`` recomputes the trace internally and throws the
+  result away ; downstream bricks (``subtract_sky_2d``,
+  ``correct_smile_polynomial`` reference_row, ``correct_slant_affine``
+  pivot_row) take it as a hand-tuned parameter. ``detect_trace`` makes
+  the automatic-reduction preset feasible. Tody 1986 SPIE 627 733
+  (IRAF ``apall`` / ``aptrace``).
+- **`measure_arc_geometry`** — measure ``smile_radius`` and
+  ``slant_deg`` directly from an arc-lamp 2-D pose. The two geometry
+  correctors (``correct_smile_polynomial``, ``correct_slant_affine``)
+  consume them but until now had no measurement step ; they were
+  hand-tuned. The brick tracks each detected arc line row-by-row
+  across the slit, then fits one common Schroeder parabola + linear
+  tilt slope. Pairs with ``detect_trace`` (uses the science trace as
+  the reference row ``y₀``). IRAF ``identify/reidentify/fitcoords``
+  heritage (Tody 1986) ; PypeIt wavelength/tilts module (Prochaska et
+  al. 2020 JOSS 5 2308) ; Schroeder 2000 ch. 15 §15.3 for the smile
+  parametrisation.
+
+### Improved — cross-references in extraction docstrings
+
+The ``long_description`` of both ``extract_spectrum_boxcar`` and
+``extract_spectrum_optimal`` now point at each other, so users can
+choose between them with the precise scientific criterion (SNR
+regime, need for uncertainty propagation, cosmic-ray residuals)
+spelled out in the catalogue.
+
+### Numbers
+
+**105 algorithms** registered after this release (was 98). **294
+tests** pass (35 new), 2 skipped. ``ruff`` clean, ``mkdocs build
+--strict`` clean, ``twine check --strict`` clean.
+
+## [0.2.1] — 2026-06-09
+
+End-to-end aurora-parity patch. Diagnosed and validated bit-exactly on
+real M42 long-slit data: with these two changes a downstream aurora
+reduction pipeline running entirely on spectro-kernel matches its
+science-core baseline at **Pearson 0.99996** (median |Δ| 0.82 %),
+where v0.2.0 alone scored 0.107 (output silently shifted by +32768 ADU
+on every step).
+
+### Fixed — uint16 ``BZERO``/``BSCALE`` leak in the easyspec staging helpers (BUG)
+
+The shared helper ``stage_target`` in
+[`reduction/_easyspec_apply.py`](src/spectro_kernel/algorithms/reduction/_easyspec_apply.py)
+wrote ``ctx.image.data`` as float64 on a new ``PrimaryHDU`` and copied
+the source header verbatim. When the source frame originated from a
+**uint16 raw file** (``BITPIX=16``, ``BZERO=32768``, ``BSCALE=1`` —
+astropy's convention), the scaling keywords landed on the float64 HDU
+and astropy then re-applied them on read-back, **silently adding 32768
+ADU to every pixel**. The companion ``build_corrected_imageframe``
+re-attached the same scaling block to the corrected ``ImageFrame``, so
+the next pipeline step that re-staged it inherited the leak.
+
+The fix strips a small set of reserved / scaling keywords —
+``SIMPLE, BITPIX, EXTEND, BZERO, BSCALE, BLANK, END, NAXIS*, PCOUNT,
+GCOUNT, XTENSION`` — before they reach either the staged HDU or the
+header re-attached downstream. astropy re-derives the structural keys
+from the data itself; the non-structural metadata (``EXPTIME``,
+``OBSERVER``, etc.) survives.
+
+Affects all four easyspec apply wrappers in one shot:
+``subtract_bias_easyspec``, ``subtract_dark_easyspec``,
+``flat_normalize_easyspec``, ``extract_spectrum_easyspec``. Native-numpy
+algorithms (``dark_subtract``, ``flat_normalize``, ``subtract_sky_2d``,
+the v0.2.0 geometry / denoising suite) were never affected — they
+operate directly on ``ctx.image.data`` without round-tripping through a
+FITS file.
+
+5 regression tests added in
+[`tests/unit/test_easyspec_apply_staging.py`](tests/unit/test_easyspec_apply_staging.py).
+
+### Added — ``extract_spectrum_boxcar`` (literature aperture extraction)
+
+New algorithm in
+[`algorithms/extraction/boxcar.py`](src/spectro_kernel/algorithms/extraction/boxcar.py).
+Same easyspec tracing step as ``extract_spectrum_easyspec``, but
+extraction is a **pure-numpy aperture sum** (clamped to the detector
+bounds on every column).
+
+Why a new brick: ``extract_spectrum_easyspec`` delegates the extraction
+to ``easyspec.extracting``, whose per-column internal sky window
+crashes with ``ValueError: broadcast (W,) vs (S,)`` when the aperture
+half-width is wide (≥ a few hundred px) and the trace sits near a
+detector edge — the typical aurora / extended-source geometry. The new
+brick keeps easyspec's argmax tracing (the trace itself is fine) but
+performs the aperture sum in numpy, with ``max(0, …)`` / ``min(rows,
+…)`` clipping on every column so it is **edge-safe by construction**.
+
+Supports two weightings:
+
+- ``"tophat"`` — unweighted box sum (standard IRAF ``apall``).
+- ``"gaussian"`` — profile-weighted Horne 1986 estimator (the average
+  column profile is fit with ``astropy.modeling`` to derive the
+  weights).
+
+``shift_y_pixels = 0`` disables the background subtraction (pure
+column sum); a positive value samples sky from two symmetric flanking
+windows. References: **Horne 1986, PASP 98, 609** ; **Tody 1986, Proc.
+SPIE 627, 733** (IRAF ``apall`` / ``aptrace``). easyspec is imported
+lazily inside ``run()`` (v0.1.5+ pattern).
+
+6 tests in
+[`tests/unit/test_extract_boxcar.py`](tests/unit/test_extract_boxcar.py),
+including the wide-aperture edge case that motivated the brick.
+
+### Numbers
+
+**98 algorithms** registered (was 97). 254 tests pass (11 new), 3
+skipped. ``ruff check`` clean, ``mkdocs build --strict`` clean,
+``twine check --strict`` clean.
+
 ## [0.2.0] — 2026-06-09
 
 A library expansion focused on long-slit reduction (aurora, stellar,

{spectro_kernel-0.2.0 → spectro_kernel-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spectro-kernel
-Version: 0.2.0
+Version: 0.3.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://matthieulel.github.io/spectro-kernel/

{spectro_kernel-0.2.0 → spectro_kernel-0.3.0}/docs/tutorials/long-slit-reduction.md

@@ -63,8 +63,11 @@ steps:
       band_below_hi: 160
   - algorithm: subtract_sky_2d
     params: {trace_row: 120, trace_half_width: 6, sky_offset: 4, sky_half_width: 10}
-  - algorithm: extract_spectrum_sum
-    params: {trace_row: 120, half_width: 6}
+  # extract_spectrum_boxcar is the edge-safe boxcar for extended sources
+  # (aurora, nebulae). For a stellar point source, extract_spectrum_sum
+  # or extract_spectrum_easyspec are also valid choices.
+  - algorithm: extract_spectrum_boxcar
+    params: {trace_method: "argmax", trace_half_width: 6, extraction_weights: "tophat", shift_y_pixels: 0}
 
   # ── 4. In-situ wavelength calibration from the simultaneously-acquired
   #     sky reference (no arc lamp needed).

spectro_kernel-0.3.0/src/spectro_kernel/algorithms/corrections/response_from_standard.py

@@ -0,0 +1,291 @@
+"""Algorithm: build the instrumental-response curve from a standard star.
+
+Closes the flux-calibration loop in the native (non-easyspec) chain.
+The recipe is the textbook standard-star method (Oke 1990, Bessell
+1999, Hamuy 1992/1994) :
+
+1. Take the observed standard ``ctx.spectrum`` — already wavelength-
+   calibrated, ideally already extinction-corrected.
+2. Take the catalogue spectrum from ``ctx.extras["catalog_spectrum"]``
+   (e.g. a CALSPEC / Oke star, loaded via the existing ``read_*``
+   readers or fetched manually upstream).
+3. Resample the catalogue to the observed wavelength grid and compute
+   the ratio ``observed / catalog``. This is the **raw** sensitivity
+   curve (instrument + telescope + atmosphere combined).
+4. Mask Balmer + telluric windows (configurable via
+   ``exclude_regions``). These features are intrinsic to the source or
+   the atmosphere — keeping them in the fit would imprint their wings
+   into the response.
+5. Fit a low-frequency smoother (spline or polynomial) to the masked
+   ratio. The smoother captures the broad sensitivity envelope without
+   chasing line residuals.
+6. Optionally apply an extinction correction first, when the user
+   supplies an ``airmass``. The default is to assume the input has
+   already been extinction-corrected (the spec's recommendation; pair
+   with ``extinction_correct_easyspec`` upstream).
+
+The resulting response is written to
+``ctx.extras["reference_spectrum"]`` so the existing
+``combine_spectra_arithmetic(operation="div")`` brick consumes it
+directly as the "second spectrum" — same idiom as
+``remove_telluric_division``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+from scipy.interpolate import UnivariateSpline
+
+from ...base import AlgorithmOutput, BaseAlgorithm
+from ...errors import InvalidParameterError
+from ...registry import register_algorithm
+from ...types import AlgorithmCategory, Spectrum1D, WorkContext
+
+# Default exclude windows: Balmer lines + main visible telluric bands.
+# These are conservative widths suitable for amateur resolutions
+# (Alpy 600 ~ 11 Å, Star'Ex LR ~ 4 Å). User can override entirely.
+_DEFAULT_EXCLUDE_REGIONS_ANGSTROM: tuple[tuple[float, float], ...] = (
+    (3960.0, 3985.0),   # Ca II H + Hε blend
+    (3925.0, 3945.0),   # Ca II K
+    (4090.0, 4115.0),   # Hδ
+    (4330.0, 4355.0),   # Hγ
+    (4850.0, 4875.0),   # Hβ
+    (5870.0, 5900.0),   # Na D
+    (6540.0, 6585.0),   # Hα (+ [N II])
+    (6860.0, 6960.0),   # O₂ B-band telluric
+    (7150.0, 7350.0),   # H₂O telluric
+    (7580.0, 7700.0),   # O₂ A-band telluric
+)
+
+_OKE = "Oke 1990, AJ 99, 1621 — flux calibration with secondary standards."
+_BESSELL = "Bessell 1999, PASP 111, 1426 — UBVRI flux standards review."
+_HAMUY = (
+    "Hamuy et al. 1992 PASP 104, 533 + 1994 PASP 106, 566 — Southern "
+    "spectrophotometric standards."
+)
+_BOHLIN = "Bohlin et al. 2014, PASP 126, 711 — CALSPEC HST standard stars."
+_HAYES_LATHAM = "Hayes & Latham 1975, ApJ 197, 593 — mean atmospheric extinction."
+
+
+def _build_mask(
+    wavelength: np.ndarray, exclude_regions: list[tuple[float, float]],
+) -> np.ndarray:
+    """Boolean keep-mask : True where the sample is NOT in any exclude window."""
+    keep = np.ones(wavelength.shape, dtype=bool)
+    for lo, hi in exclude_regions:
+        keep &= ~((wavelength >= float(lo)) & (wavelength <= float(hi)))
+    return keep
+
+
+def _sigma_clip_residuals(
+    x: np.ndarray, y: np.ndarray, fit_values: np.ndarray, sigma: float,
+) -> np.ndarray:
+    """Keep samples whose residual lies within ±σ of the fit."""
+    res = y - fit_values
+    rms = float(np.sqrt(np.nanmean(res ** 2)))
+    if rms == 0.0:
+        return np.ones(x.shape, dtype=bool)
+    return np.abs(res) <= sigma * rms
+
+
+@register_algorithm(
+    "response_from_standard",
+    category=AlgorithmCategory.FLUX_CALIBRATION,
+    version="1.0.0",
+)
+class ResponseFromStandard(BaseAlgorithm):
+    """Derive the instrumental response curve from a standard-star observation.
+
+    Input contract :
+
+    - ``ctx.spectrum`` — the observed standard, wavelength-calibrated in
+      Ångström. Recommended : already extinction-corrected (via
+      ``extinction_correct_easyspec`` or equivalent).
+    - ``ctx.extras["catalog_spectrum"]`` — the catalogue spectrum of
+      the same standard (CALSPEC / Oke / MILES …), as a
+      :class:`Spectrum1D`. The wavelength grid does not need to match
+      the observed grid ; the algorithm resamples by linear
+      interpolation.
+
+    Output : ``ctx.extras["reference_spectrum"]`` — the smoothed
+    sensitivity curve on the observed wavelength grid. Feeds directly
+    into ``combine_spectra_arithmetic(operation="div")``.
+    """
+
+    backend = "scipy"
+    references = [_OKE, _BESSELL, _HAMUY, _BOHLIN, _HAYES_LATHAM]
+    long_description = (
+        "Computes observed / catalog (after resampling the catalogue to "
+        "the observed grid), masks Balmer + telluric windows, σ-clips, "
+        "fits a low-frequency spline (default) or polynomial. The "
+        "spline knot count controls the smoothness — too many knots "
+        "carve real features into the response, too few miss instrument "
+        "structure. Sensible defaults : 20 knots for the full visible. "
+        "Catalogue spectrum lives in ctx.extras['catalog_spectrum'], "
+        "consistent with the second-spectrum idiom used by "
+        "remove_telluric_division and combine_spectra_arithmetic."
+    )
+    default_params: dict[str, Any] = {
+        "fit": "spline",
+        "spline_knots": 20,
+        "poly_order": 5,
+        "exclude_regions": None,        # None = use _DEFAULT_EXCLUDE_REGIONS_ANGSTROM
+        "sigma_clip": 3.0,
+        "max_iter": 3,
+        "catalog_key": "catalog_spectrum",
+        "output_key": "reference_spectrum",
+    }
+    required_params: list[str] = []
+    param_descriptions = {
+        "fit": "'spline' (default low-frequency UnivariateSpline) or 'polynomial'.",
+        "spline_knots": (
+            "Number of interior knots for the spline fit. More knots ⇒ "
+            "tighter fit (risks eating real features) ; fewer ⇒ smoother."
+        ),
+        "poly_order": "Polynomial order when fit='polynomial'.",
+        "exclude_regions": (
+            "List of (wave_lo, wave_hi) windows (Å) to exclude from the "
+            "fit. None ⇒ a default set covering Balmer + visible "
+            "telluric bands."
+        ),
+        "sigma_clip": "σ threshold for residual clipping during the fit (≥ 1).",
+        "max_iter": "Maximum σ-clip iterations.",
+        "catalog_key": "ctx.extras key holding the catalogue Spectrum1D.",
+        "output_key": "ctx.extras key receiving the fitted response curve.",
+    }
+    input_requirements = ["spectrum"]
+    output_produces = ["extras.reference_spectrum", "metrics.response_rms"]
+
+    def run(self, ctx: WorkContext, params: dict[str, Any]) -> AlgorithmOutput:
+        if ctx.spectrum is None:
+            return AlgorithmOutput.fail("No ctx.spectrum (the observed standard).")
+        catalog_key = str(params["catalog_key"])
+        catalog = ctx.extras.get(catalog_key)
+        if not isinstance(catalog, Spectrum1D):
+            return AlgorithmOutput.fail(
+                f"Catalogue spectrum missing at ctx.extras[{catalog_key!r}]."
+            )
+        fit = str(params["fit"])
+        if fit not in ("spline", "polynomial"):
+            raise InvalidParameterError("fit must be 'spline' or 'polynomial'.")
+
+        observed = ctx.spectrum
+        wave = np.asarray(observed.wavelength, dtype=np.float64)
+        obs_flux = np.asarray(observed.flux, dtype=np.float64)
+        if wave.size < 16:
+            return AlgorithmOutput.fail(
+                "Observed spectrum too short to build a response."
+            )
+
+        # Resample catalogue to the observed grid (NaN outside its domain).
+        cat_flux = np.interp(
+            wave,
+            np.asarray(catalog.wavelength, dtype=np.float64),
+            np.asarray(catalog.flux, dtype=np.float64),
+            left=np.nan, right=np.nan,
+        )
+
+        # Raw response = observed / catalog. NaN/zero-safe.
+        with np.errstate(divide="ignore", invalid="ignore"):
+            raw_response = obs_flux / cat_flux
+        valid = np.isfinite(raw_response) & (cat_flux > 0.0)
+
+        # Apply user-supplied exclude regions on top of validity mask.
+        excludes = params.get("exclude_regions")
+        if excludes is None:
+            excludes = list(_DEFAULT_EXCLUDE_REGIONS_ANGSTROM)
+        excludes = [(float(lo), float(hi)) for lo, hi in excludes]
+        keep = valid & _build_mask(wave, excludes)
+        if int(keep.sum()) < max(int(params["spline_knots"]) + 4, 8):
+            return AlgorithmOutput.fail(
+                f"Only {int(keep.sum())} valid samples after masking — "
+                "loosen exclude_regions or lower spline_knots."
+            )
+
+        sigma_clip = float(params["sigma_clip"])
+        max_iter = int(params["max_iter"])
+
+        if fit == "spline":
+            knots = max(4, int(params["spline_knots"]))
+            for _ in range(max_iter):
+                x_fit = wave[keep]
+                y_fit = raw_response[keep]
+                try:
+                    spline = UnivariateSpline(
+                        x_fit, y_fit, k=3, s=len(x_fit),
+                    )
+                    # Choose knot count by clamping the smoothing factor: a
+                    # smaller s gives more knots. We tune s so the spline
+                    # uses roughly `knots` internal knots.
+                    span = float(np.var(y_fit)) * len(x_fit)
+                    spline.set_smoothing_factor(max(span / max(knots, 1), 1e-9))
+                except Exception as exc:  # noqa: BLE001
+                    return AlgorithmOutput.fail(
+                        f"Spline fit failed: {type(exc).__name__}: {exc}"
+                    )
+                fit_values = spline(x_fit)
+                new_keep_in = _sigma_clip_residuals(
+                    x_fit, y_fit, fit_values, sigma_clip,
+                )
+                if int(new_keep_in.sum()) <= knots + 4:
+                    break
+                # Update outer mask in-place (mask is reduced, never grown).
+                inner = np.where(keep)[0]
+                keep = np.zeros_like(keep)
+                keep[inner[new_keep_in]] = True
+            response = spline(wave)
+        else:  # polynomial
+            order = int(params["poly_order"])
+            for _ in range(max_iter):
+                x_fit = wave[keep]
+                y_fit = raw_response[keep]
+                coef = np.polyfit(x_fit, y_fit, order)
+                fit_values = np.polyval(coef, x_fit)
+                new_keep_in = _sigma_clip_residuals(
+                    x_fit, y_fit, fit_values, sigma_clip,
+                )
+                if int(new_keep_in.sum()) <= order + 1:
+                    break
+                inner = np.where(keep)[0]
+                keep = np.zeros_like(keep)
+                keep[inner[new_keep_in]] = True
+            response = np.polyval(coef, wave)
+
+        # Build the response Spectrum1D, marked as such for downstream.
+        reference = Spectrum1D(
+            wavelength=wave,
+            flux=response.astype(np.float64),
+            flux_unit="response",
+            wavelength_unit=observed.wavelength_unit,
+            meta={
+                "kind": "instrumental_response",
+                "derived_from": "response_from_standard",
+                "fit": fit,
+                "n_fit_samples": int(keep.sum()),
+                "exclude_regions_angstrom": excludes,
+            },
+        )
+        output_key = str(params["output_key"])
+        ctx.extras[output_key] = reference
+
+        residuals = raw_response[keep] - response[keep]
+        rms = float(np.sqrt(np.nanmean(residuals ** 2))) if residuals.size else 0.0
+        ctx.metrics["response_rms"] = rms
+        return AlgorithmOutput.ok(
+            metrics={
+                "response_rms": rms,
+                "n_fit_samples": float(int(keep.sum())),
+                "median_response": float(np.nanmedian(response)),
+            },
+            artifacts={
+                "fit_method": fit,
+                "exclude_regions_angstrom": excludes,
+                "output_key": output_key,
+            },
+            message=(
+                f"Response derived ({fit}, {int(keep.sum())} samples used, "
+                f"RMS={rms:.4g})."
+            ),
+        )