spectro-kernel 0.4.0__tar.gz → 0.5.0__tar.gz

{spectro_kernel-0.4.0 → spectro_kernel-0.5.0}/CHANGELOG.md

@@ -6,6 +6,140 @@ Until `1.0.0` the public API may change between minor versions.
 
 ## [Unreleased]
 
+## [0.5.0] — 2026-06-26
+
+Second-pass enrichment driven by the STAROS dashboard's delegation
+checklist (`stuff/spectro_kernel_requests_25_06_26.md`). Six
+focused improvements across the radial-velocity, kinematics,
+continuum, and time-series stacks — two correctness fixes that
+warrant a MAJOR bump on the individual algorithm, four ergonomic
+extensions, and a reciprocal documentation cross-reference.
+
+Public API additions only — no parameter renamed or removed. The
+two algorithms whose internal numerics change (`cross_correlate_rv`,
+`rotation_curve`) ship explicit opt-outs that preserve the v0.4.1
+behaviour bit-for-bit.
+
+### Changed — `cross_correlate_rv` v1.2.0 → v2.0.0
+
+- **Continuum subtraction is now ON by default.** Tonry & Davis
+  1979 §III require continuum-normalised inputs ; the previous
+  mean-only centring biased the CCF on raw stellar fluxes with a
+  sloped SED (verified empirically : on a synthetic G-type-like
+  template shifted by +100 km/s the recovered RV climbed from
+  ~+40 km/s to ~+100 km/s with the new default).
+- New parameters ``continuum_subtract`` (default ``True``) and
+  ``continuum_window`` (default 101 pixels, running median).
+- Set ``continuum_subtract=False`` to recover the v1.x behaviour
+  bit-for-bit (covered by a regression test).
+- Long description now cross-references `rv_precision_bouchy` for
+  the photon-noise floor — pair the empirical CCF error with the
+  Bouchy floor to read your RV systematics budget.
+
+### Changed — `rotation_curve` v1.0.0 → v2.0.0
+
+- **Per-spectrum traceability.** The brick used to drop failed or
+  missing-offset spectra silently from the points list ; STAROS
+  needs to surface those rejections on the dashboard. The
+  ``extras["points"]`` artefact is now a ``list[dict]`` with one
+  entry per input spectrum (success OR failure) carrying
+  ``{spectrum_id, slit_offset_arcsec, v_los_kms,
+  line_fit_center_aa, note}``. Notes : ``"ok"``,
+  ``"missing slit_offset"``, ``"Hα out of range"``, ``"fit failed"``,
+  ``"empty spectrum"``.
+- ``spectrum_id`` is round-tripped from
+  ``spec.meta["spectrum_id"]`` or falls back to the input index.
+- Successful entries are sorted by slit offset ; missing-offset
+  entries are appended at the tail.
+- When fewer than 3 fits succeed the algorithm still fails, but
+  the per-spectrum breakdown is exposed in ``extras["points"]`` so
+  the dashboard can report which spectra are blocking the fit.
+
+### Changed — `normalize_polynomial` v1.0.0 → v1.1.0
+
+- New ``sigma_low`` and ``sigma_high`` parameters for **asymmetric
+  sigma-clipping** (IRAF ``low_reject`` / ``high_reject`` heritage,
+  Tody 1986, Proc. SPIE 627, 733). Amateur stellar spectra are
+  dominated by absorption ; a symmetric clip wrongly treats those
+  lines as noise and biases the continuum downwards. Pass
+  ``sigma_low=1.5, sigma_high=3.0`` to protect the continuum from
+  absorption-line population.
+- New ``windows`` parameter — list of ``(λ_lo, λ_hi)`` intervals
+  restricting the fit to user-specified continuum windows (IRAF
+  ``sample`` parameter).
+- When ``sigma_low``, ``sigma_high`` and ``windows`` are all left
+  at their defaults the brick routes through the legacy helper —
+  v1.0.0 callers stay bit-identical.
+
+### Changed — `measure_radial_velocity` v1.0.0 → v1.1.0
+
+- New ``profile`` parameter ∈ ``{"gaussian", "lorentzian", "voigt"}``
+  forwarded to the existing ``fit_line`` helper. Default ``"gaussian"``
+  preserves v1.0.0 behaviour. Use ``"lorentzian"`` for damped wings
+  (Hα in cool stars) and ``"voigt"`` when neither pure Doppler nor
+  pure collisional broadening fits.
+
+### Changed — `lomb_scargle` v1.0.0 → v1.1.0
+
+- New ``normalization`` parameter ∈
+  ``{"standard", "model", "log", "psd"}`` forwarded verbatim to
+  ``astropy.timeseries.LombScargle`` (default ``"standard"``
+  preserves v1.0.0 behaviour). Use ``"psd"`` to stitch with
+  classical Fourier-domain tooling ; the peak frequency is
+  invariant under the choice of normalisation.
+- The chosen normalisation is echoed in
+  ``periodogram.meta["normalization"]``.
+- Doc note about composing with the existing ``phase_fold`` brick :
+  feed ``ctx.metrics["best_period"]`` to ``phase_fold`` to render
+  the folded light curve.
+
+### Changed — `rv_precision_bouchy` v1.0.0 → v1.0.1
+
+- Documentation only. Long description and references now point at
+  `cross_correlate_rv` reciprocally — pair the photon-noise floor
+  (Bouchy 2001) with the empirical Tonry & Davis CCF error to
+  characterise the RV systematics budget.
+
+### Numbers
+
+113 algorithms (unchanged). 343 tests pass (12 new), ruff clean.
+
+## [0.4.1] — 2026-06-26
+
+Backwards-compatible extension of `cross_correlate_rv` so downstream
+RV consumers can delegate to the kernel without losing the
+peak-confidence / error / CCF-curve / template-provenance surface
+they currently maintain in-house.
+
+### Changed — `cross_correlate_rv` v1.1.0 → v1.2.0
+
+- The CCF is now **Pearson-normalised** so the peak height reads
+  directly as a similarity score bounded in ``[-1, 1]``.
+- New ``metrics.peak_strength`` (clamped to ``[0, 1]``) — UI-friendly
+  confidence indicator (1 ⇒ template-identical observed spectrum).
+- New ``metrics.radial_velocity_error_kms`` — the canonical
+  **Tonry & Davis 1979** §III formula
+  ``σ_v = 3 · w / (8 · (1 + r))`` with
+  ``r = h / (√2 · σ_a)`` (peak height over noise antisymmetry RMS)
+  and ``w`` the CCF peak FWHM. Reports ``NaN`` when the CCF shape
+  forbids a clean estimate (no resolved peak, no antisymmetric
+  noise sample).
+- New ``extras["ccf"] = {"lags_kms": [...], "ccf": [...]}`` — the CCF
+  curve restricted to the velocity search window, for downstream
+  plotting.
+- New ``extras["template_id"]`` — best-effort label of the template
+  used (file basename for ``template_path``, key name for
+  ``template_key``).
+- Pre-existing output ``metrics.radial_velocity_kms`` is preserved
+  bit-exact ; the ``v1.2.0`` bump reflects the *additions*. A
+  regression test (`tests/reference/test_known_answers.py`) covers
+  the existing 50 km/s recovery.
+
+### Numbers
+
+113 algorithms (unchanged). 331 tests pass (6 new), ruff clean,
+mkdocs strict OK, twine strict OK.
+
 ## [0.4.0] — 2026-06-26
 
 A scientific catalogue expansion driven by a downstream

{spectro_kernel-0.4.0 → spectro_kernel-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spectro-kernel
-Version: 0.4.0
+Version: 0.5.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.5.0/src/spectro_kernel/algorithms/continuum/normalize_polynomial.py

@@ -0,0 +1,242 @@
+"""Algorithm: normalise a spectrum by a sigma-clipped polynomial continuum.
+
+Iterative polynomial continuum fit with optional **asymmetric**
+sigma-clipping (``sigma_low`` / ``sigma_high``) and optional explicit
+**continuum windows** (``windows``). The defaults reproduce the
+v1.0.0 symmetric-clip behaviour (``sigma_low = sigma_high = sigma``,
+no windows).
+
+References
+----------
+- IRAF ``continuum`` task — symmetric and asymmetric ``low_reject`` /
+  ``high_reject``, ``sample`` (wavelength windows) ; **Tody 1986**,
+  Proc. SPIE 627, 733.
+- Sigma-clipping iterative fit — standard robust-regression practice
+  in astronomical reduction pipelines.
+"""
+
+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
+from .._common import fit_polynomial_continuum
+
+
+def _windows_mask(wavelength: np.ndarray, windows: list[tuple[float, float]]) -> np.ndarray:
+    """Boolean mask : samples inside ANY of the (lo, hi) wavelength windows."""
+    mask = np.zeros_like(wavelength, dtype=bool)
+    for lo, hi in windows:
+        lo, hi = (float(lo), float(hi)) if lo <= hi else (float(hi), float(lo))
+        mask |= (wavelength >= lo) & (wavelength <= hi)
+    return mask
+
+
+def _fit_polynomial_continuum_extended(
+    wavelength: np.ndarray,
+    flux: np.ndarray,
+    *,
+    order: int,
+    sigma_low: float,
+    sigma_high: float,
+    iterations: int,
+    windows: list[tuple[float, float]] | None,
+) -> np.ndarray:
+    """Continuum fit with asymmetric clip + optional wavelength windows.
+
+    Per-iteration:
+      1. Fit a polynomial on the currently-kept samples.
+      2. Compute residuals = flux − continuum.
+      3. Keep samples whose residual ∈ ``[-sigma_low · σ, +sigma_high · σ]``.
+
+    ``windows`` (when given) restricts the initial-mask to samples inside
+    at least one user-specified wavelength interval — the polynomial is
+    then fitted **only on those samples**, but evaluated everywhere on
+    ``wavelength`` for the output (we still divide the whole spectrum
+    by the continuum model).
+    """
+    x = np.asarray(wavelength, dtype=np.float64)
+    y = np.asarray(flux, dtype=np.float64)
+    base_mask = np.isfinite(y)
+    if windows:
+        base_mask &= _windows_mask(x, windows)
+    mask = base_mask.copy()
+    if int(mask.sum()) <= order + 1:
+        # Not enough samples to fit; fall back to a flat continuum.
+        return np.full_like(y, float(np.nanmedian(y)))
+
+    for _ in range(max(1, iterations)):
+        model = np.polynomial.Polynomial.fit(x[mask], y[mask], deg=order)
+        residuals = y - model(x)
+        sigma = float(np.std(residuals[mask]))
+        if sigma == 0.0:
+            break
+        new_mask = (
+            base_mask
+            & (residuals > -sigma_low * sigma)
+            & (residuals < +sigma_high * sigma)
+        )
+        if int(new_mask.sum()) <= order + 1:
+            break
+        if np.array_equal(new_mask, mask):
+            mask = new_mask
+            break
+        mask = new_mask
+    final = np.polynomial.Polynomial.fit(x[mask], y[mask], deg=order)
+    return final(x)
+
+
+@register_algorithm(
+    "normalize_polynomial",
+    category=AlgorithmCategory.CONTINUUM,
+    # 1.1.0: asymmetric sigma_low / sigma_high + explicit windows. The
+    # default behaviour (symmetric clip, full-range fit) is unchanged.
+    version="1.1.0",
+)
+class NormalizePolynomial(BaseAlgorithm):
+    """Normalise the continuum to unity with a sigma-clipped polynomial fit.
+
+    A polynomial of the requested order is fitted to the continuum
+    (lines rejected by iterative sigma clipping) ; the flux is divided
+    by it. The result is a continuum-normalised spectrum oscillating
+    around 1.0.
+
+    Two v1.1.0 additions match the IRAF ``continuum`` toolbox :
+
+    - **Asymmetric sigma-clip** via ``sigma_low`` and ``sigma_high``.
+      Amateur stellar spectra are dominated by *absorption* lines —
+      with the symmetric default they get clipped as if they were
+      noise, biasing the continuum downwards. ``sigma_low=1.5,
+      sigma_high=3.0`` is the conservative choice for absorption-rich
+      sources (the asymmetry says "I trust the +side more than the
+      −side for telling continuum from line"). When either is left at
+      ``None`` the brick falls back to the legacy symmetric clip with
+      ``sigma_clip`` on both sides.
+    - **Explicit continuum windows** via ``windows``. A list of
+      ``(λ_lo, λ_hi)`` intervals restricts the fit to the samples
+      inside at least one window — useful when the user knows where
+      the line-free regions are (Mg b avoidance, telluric avoidance).
+      Disabled by default ; the polynomial then sees the whole
+      spectrum and reduction is via the sigma-clip.
+    """
+
+    backend = "numpy"
+    references = [
+        "Tody 1986, Proc. SPIE 627, 733 — IRAF continuum task "
+        "(low_reject / high_reject / sample heritage).",
+    ]
+    long_description = (
+        "Use a low order (2-4) for a slowly varying continuum; higher "
+        "orders risk absorbing real spectral features. For "
+        "absorption-line-rich sources set sigma_low=1.5, sigma_high=3."
+    )
+    default_params = {
+        "order": 3,
+        "sigma_clip": 3.0,
+        "sigma_low": None,
+        "sigma_high": None,
+        "iterations": 3,
+        "windows": None,
+    }
+    param_descriptions = {
+        "order": "Polynomial degree of the continuum fit.",
+        "sigma_clip": (
+            "Symmetric clip threshold (default 3.0). Used as a fallback "
+            "for sigma_low / sigma_high when those are left at None."
+        ),
+        "sigma_low": (
+            "Asymmetric clip threshold on the LOW side (rejects "
+            "absorption lines). None ⇒ falls back to sigma_clip."
+        ),
+        "sigma_high": (
+            "Asymmetric clip threshold on the HIGH side (rejects "
+            "emission lines / cosmics). None ⇒ falls back to sigma_clip."
+        ),
+        "iterations": "Number of sigma-clipping iterations.",
+        "windows": (
+            "Optional list of (λ_lo, λ_hi) wavelength intervals ; when "
+            "given, the polynomial is fitted only on samples inside at "
+            "least one window (IRAF 'sample' parameter)."
+        ),
+    }
+    input_requirements = ["spectrum"]
+    output_produces = ["spectrum", "metrics.continuum_median"]
+
+    def run(self, ctx: WorkContext, params: dict[str, Any]) -> AlgorithmOutput:
+        spec = ctx.spectrum
+        order = int(params["order"])
+        sigma_clip = float(params["sigma_clip"])
+        iterations = int(params["iterations"])
+        if iterations < 1:
+            raise InvalidParameterError("iterations must be ≥ 1.")
+        sigma_low_raw = params.get("sigma_low")
+        sigma_high_raw = params.get("sigma_high")
+        sigma_low = float(sigma_low_raw) if sigma_low_raw is not None else sigma_clip
+        sigma_high = float(sigma_high_raw) if sigma_high_raw is not None else sigma_clip
+        if sigma_low <= 0.0 or sigma_high <= 0.0:
+            raise InvalidParameterError("sigma thresholds must be strictly positive.")
+
+        windows_param = params.get("windows")
+        windows: list[tuple[float, float]] | None = None
+        if windows_param:
+            windows = [(float(lo), float(hi)) for lo, hi in windows_param]
+
+        # When the defaults are in play AND no windows AND no asymmetry,
+        # we route through the legacy helper so v1.0.0 callers stay
+        # bit-identical (the iterative-mask convergence criterion
+        # differs subtly between the two helpers).
+        symmetric_default = (
+            windows is None
+            and sigma_low_raw is None
+            and sigma_high_raw is None
+        )
+        if symmetric_default:
+            continuum = fit_polynomial_continuum(
+                spec.wavelength,
+                spec.flux,
+                order=order,
+                sigma_clip=sigma_clip,
+                iterations=iterations,
+            )
+        else:
+            continuum = _fit_polynomial_continuum_extended(
+                np.asarray(spec.wavelength, dtype=np.float64),
+                np.asarray(spec.flux, dtype=np.float64),
+                order=order,
+                sigma_low=sigma_low,
+                sigma_high=sigma_high,
+                iterations=iterations,
+                windows=windows,
+            )
+        safe = np.where(continuum == 0.0, np.nan, continuum)
+        normalised = spec.flux / safe
+
+        out = spec.with_flux(normalised, flux_unit="normalized")
+        if spec.uncertainty is not None:
+            out.uncertainty = spec.uncertainty / np.abs(safe)
+        out.meta["continuum_method"] = "polynomial"
+        out.meta["continuum_sigma_low"] = sigma_low
+        out.meta["continuum_sigma_high"] = sigma_high
+        if windows:
+            out.meta["continuum_windows"] = windows
+        ctx.spectrum = out
+
+        metrics = {
+            "continuum_median": float(np.nanmedian(continuum)),
+            "normalized_rms": float(np.nanstd(normalised)),
+            "sigma_low": sigma_low,
+            "sigma_high": sigma_high,
+        }
+        return AlgorithmOutput.ok(
+            metrics=metrics,
+            message=(
+                "Continuum normalised to unity "
+                f"(σ_low={sigma_low:g}, σ_high={sigma_high:g}, "
+                f"{len(windows) if windows else 0} window(s))."
+            ),
+        )

{spectro_kernel-0.4.0 → spectro_kernel-0.5.0}/src/spectro_kernel/algorithms/kinematics/rotation_curve.py

@@ -101,7 +101,11 @@ def _slit_offset(spec: Spectrum1D, fallback_offsets: dict[int, float], idx: int)
 @register_algorithm(
     "rotation_curve",
     category=AlgorithmCategory.KINEMATICS,
-    version="1.0.0",
+    # 2.0.0: ctx.extras["points"] schema changed from list[tuple] to
+    # list[dict] with per-spectrum spectrum_id + note (status); every
+    # input spectrum produces one entry even on failure, so callers
+    # can keep their per-spectrum traceability when delegating.
+    version="2.0.0",
 )
 class RotationCurve(BaseAlgorithm):
     """Projected long-slit rotation curve v_los(r) from Hα per slit offset.
@@ -111,18 +115,26 @@ class RotationCurve(BaseAlgorithm):
     arcsec from the galactic centre) from either
     ``spec.meta["slit_offset_arcsec"]`` or
     ``params["slit_offsets"]`` (an explicit ``{index: arcsec}`` mapping),
-    fits Hα in each, and emits an offset-sorted ``v_los(r)`` rotation
-    curve in ``ctx.extras["points"]``. The systemic velocity is the
-    median of the surviving measurements.
-
-    Validity : needs ≥ 3 spectra ; spectra without a slit offset, or
-    where Hα cannot be fit, are silently dropped (the algorithm
-    reports the count in ``metrics``). Fails if zero usable
-    measurements remain.
-
-    This is the **simple projected** rotation curve — no inclination
-    correction, no asymmetric drift, no 2-D model. See ``Sofue &
-    Rubin 2001`` for the modelling extensions.
+    fits Hα in each, and emits a per-spectrum rotation curve in
+    ``ctx.extras["points"]``. The systemic velocity is the median of
+    the successful measurements.
+
+    Output shape (v2.0.0)
+    ---------------------
+    ``ctx.extras["points"] = [{spectrum_id, slit_offset_arcsec,
+    v_los_kms, line_fit_center_aa, note}]`` — **one entry per input
+    spectrum**, regardless of success. ``v_los_kms`` and
+    ``line_fit_center_aa`` are ``None`` on failure ; ``note`` is one
+    of ``"ok"`` / ``"missing slit_offset"`` / ``"Hα out of range"`` /
+    ``"fit failed"`` / ``"empty spectrum"``. Entries sort by slit
+    offset ; missing-offset entries land at the end. ``spectrum_id``
+    is read from ``spec.meta["spectrum_id"]`` when present, otherwise
+    the integer position in ``ctx.spectra`` is used.
+
+    Validity : needs ≥ 3 spectra ; fails if zero successful Hα fits
+    remain. This is the **simple projected** rotation curve — no
+    inclination correction, no asymmetric drift, no 2-D model. See
+    ``Sofue & Rubin 2001`` for the modelling extensions.
     """
 
     backend = "scipy"
@@ -172,47 +184,78 @@ class RotationCurve(BaseAlgorithm):
 
         lam_obs_rest = lam_rest * (1.0 + z)
 
-        points: list[tuple[float, float, float]] = []  # (r_arcsec, v_los_kms, mu_aa)
+        # Per-spectrum dict — one entry per input regardless of success.
+        # 'note' encodes the per-row status so downstream code can
+        # surface partial-success reductions instead of silently
+        # losing failed spectra.
+        points: list[dict[str, Any]] = []
         skipped_no_offset = 0
         skipped_no_fit = 0
         for idx, spec in enumerate(spectra):
+            spectrum_id = (
+                spec.meta.get("spectrum_id") if spec.meta else None
+            ) or idx
+            entry: dict[str, Any] = {
+                "spectrum_id": spectrum_id,
+                "slit_offset_arcsec": None,
+                "v_los_kms": None,
+                "line_fit_center_aa": None,
+                "note": "ok",
+            }
+
             offset = _slit_offset(spec, slit_offsets, idx)
             if offset is None:
                 skipped_no_offset += 1
+                entry["note"] = "missing slit_offset"
+                points.append(entry)
                 continue
+            entry["slit_offset_arcsec"] = float(offset)
+
             wave = np.asarray(spec.wavelength, dtype=np.float64)
             flux = np.asarray(spec.flux, dtype=np.float64)
             if wave.size == 0:
                 skipped_no_fit += 1
+                entry["note"] = "empty spectrum"
+                points.append(entry)
                 continue
             if lam_obs_rest < float(wave[0]) or lam_obs_rest > float(wave[-1]):
                 skipped_no_fit += 1
+                entry["note"] = "Hα out of range"
+                points.append(entry)
                 continue
             mu = _fit_halpha_centre(wave, flux, lam_obs_rest, fit_window)
             if mu is None:
                 skipped_no_fit += 1
+                entry["note"] = "fit failed"
+                points.append(entry)
                 continue
-            v_los = _SPEED_OF_LIGHT_KMS * (mu / lam_obs_rest - 1.0)
-            points.append((float(offset), float(v_los), float(mu)))
 
-        if not points:
+            v_los = _SPEED_OF_LIGHT_KMS * (mu / lam_obs_rest - 1.0)
+            entry["v_los_kms"] = float(v_los)
+            entry["line_fit_center_aa"] = float(mu)
+            entry["note"] = "ok"
+            points.append(entry)
+
+        ok_rows = [p for p in points if p["note"] == "ok"]
+        if not ok_rows:
+            ctx.extras["points"] = self._sort_points(points)
             return AlgorithmOutput.fail(
                 f"No usable rotation measurements — skipped "
                 f"{skipped_no_offset} for missing slit_offset_arcsec and "
-                f"{skipped_no_fit} for failed Hα fit."
+                f"{skipped_no_fit} for failed Hα fit. See "
+                "ctx.extras['points'] for the per-spectrum breakdown."
             )
 
-        points.sort(key=lambda row: row[0])
-        v_arr = np.asarray([row[1] for row in points], dtype=np.float64)
+        v_arr = np.asarray([p["v_los_kms"] for p in ok_rows], dtype=np.float64)
         v_sys = float(np.median(v_arr))
 
-        ctx.extras["points"] = points
+        ctx.extras["points"] = self._sort_points(points)
         ctx.extras["method"] = (
             "Per-spectrum Hα fit; v_los = c·(μ−λ_obs_rest)/λ_obs_rest; "
             "v_systemic = median(v_los). No inclination correction."
         )
         ctx.metrics["v_systemic_km_s"] = v_sys
-        ctx.metrics["n_points"] = float(len(points))
+        ctx.metrics["n_points"] = float(len(ok_rows))
         ctx.metrics["n_skipped_no_offset"] = float(skipped_no_offset)
         ctx.metrics["n_skipped_no_fit"] = float(skipped_no_fit)
 
@@ -221,15 +264,15 @@ class RotationCurve(BaseAlgorithm):
         return AlgorithmOutput.ok(
             metrics={
                 "v_systemic_km_s": v_sys,
-                "n_points": float(len(points)),
+                "n_points": float(len(ok_rows)),
                 "n_skipped_no_offset": float(skipped_no_offset),
                 "n_skipped_no_fit": float(skipped_no_fit),
                 "v_min_km_s": v_min,
                 "v_max_km_s": v_max,
             },
-            artifacts={"points": points},
+            artifacts={"points": self._sort_points(points)},
             message=(
-                f"Rotation curve: {len(points)} usable point(s), "
+                f"Rotation curve: {len(ok_rows)} usable point(s), "
                 f"v_systemic = {v_sys:+.1f} km/s, "
                 f"v ∈ [{v_min:+.1f}, {v_max:+.1f}] km/s "
                 f"(skipped {skipped_no_offset} no-offset + "
@@ -237,5 +280,13 @@ class RotationCurve(BaseAlgorithm):
             ),
         )
 
+    @staticmethod
+    def _sort_points(points: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        """Sort per-spectrum entries by slit_offset_arcsec; offset=None at the tail."""
+        with_offset = [p for p in points if p["slit_offset_arcsec"] is not None]
+        without_offset = [p for p in points if p["slit_offset_arcsec"] is None]
+        with_offset.sort(key=lambda p: p["slit_offset_arcsec"])
+        return with_offset + without_offset
+
 
 __all__ = ["RotationCurve"]