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

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

@@ -6,6 +6,42 @@ Until `1.0.0` the public API may change between minor versions.
 
 ## [Unreleased]
 
+## [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.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spectro-kernel
-Version: 0.4.0
+Version: 0.4.1
 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.4.1/src/spectro_kernel/algorithms/rv/cross_correlate.py

@@ -0,0 +1,350 @@
+"""Algorithm: cross-correlate against a template to measure radial velocity.
+
+Standard Tonry & Davis 1979 recipe: resample observed and template
+spectra onto a common log-wavelength grid (so a sample-shift is a
+constant velocity shift), centre both at zero mean, compute the
+normalised cross-correlation function, locate the peak with sub-pixel
+parabolic refinement, and report the radial velocity.
+
+In addition to the RV itself, the brick computes :
+
+- The **CCF peak strength** in ``[0, 1]`` — Pearson-normalised peak
+  height, a 0..1 confidence score that an observer can show in a UI
+  (1 ⇒ template-identical match, 0 ⇒ uncorrelated).
+- The **RV uncertainty** in km/s, using the **Tonry & Davis 1979
+  r-value** : ``σ_v = 3 · w / (8 · (1 + r))`` with ``w`` the peak FWHM
+  and ``r = h / (√2 · σ_a)`` where ``h`` is the peak height and
+  ``σ_a`` is the RMS of the antisymmetric component of the CCF away
+  from the peak. This is the canonical RV error estimator from §III
+  of the 1979 paper.
+- The **CCF curve** itself (lags km/s + ccf values) on
+  ``ctx.extras["ccf"]`` for downstream plotting.
+- The **template identifier** on ``ctx.extras["template_id"]`` so a
+  downstream pipeline can record provenance of which template fit
+  best.
+
+References
+----------
+- **Tonry, J. & Davis, M. 1979**, AJ 84, 1511 — fundamental CCF
+  method for radial velocity ; defines the ``r`` parameter and the
+  velocity-error formula used here.
+- ``scipy.signal.correlate`` — the cross-correlation engine.
+"""
+
+from __future__ import annotations
+
+import math
+import os
+from typing import Any
+
+import astropy.constants as const
+import astropy.units as u
+import numpy as np
+from scipy.signal import correlate
+
+from ...base import AlgorithmOutput, BaseAlgorithm
+from ...io import read_fits
+from ...registry import register_algorithm
+from ...types import AlgorithmCategory, Spectrum1D, WorkContext
+
+_C_KMS = const.c.to(u.km / u.s).value
+
+# Tonry-Davis 1979 §III error coefficient: σ_v = 3 · w / (8 · (1 + r)).
+_TD_ERROR_COEF: float = 3.0 / 8.0
+
+
+def _peak_fwhm_kms(velocities: np.ndarray, ccf: np.ndarray, ipeak: int) -> float | None:
+    """FWHM (km/s) of the CCF peak above half-maximum, or None when ambiguous."""
+    if ipeak <= 0 or ipeak >= ccf.size - 1:
+        return None
+    peak = float(ccf[ipeak])
+    baseline = float(np.min(ccf))
+    if peak <= baseline:
+        return None
+    half = 0.5 * (peak + baseline)
+
+    # Walk left and right from the peak until the CCF drops below half.
+    left = ipeak
+    while left > 0 and ccf[left] >= half:
+        left -= 1
+    right = ipeak
+    while right < ccf.size - 1 and ccf[right] >= half:
+        right += 1
+    if left == ipeak or right == ipeak:
+        return None
+    # Linear interpolation at the half-max crossings for sub-bin precision.
+    if ccf[left + 1] != ccf[left]:
+        frac_left = (half - ccf[left]) / (ccf[left + 1] - ccf[left])
+        v_left = velocities[left] + frac_left * (velocities[left + 1] - velocities[left])
+    else:
+        v_left = float(velocities[left])
+    if ccf[right - 1] != ccf[right]:
+        frac_right = (half - ccf[right]) / (ccf[right - 1] - ccf[right])
+        v_right = velocities[right] + frac_right * (velocities[right - 1] - velocities[right])
+    else:
+        v_right = float(velocities[right])
+    return float(abs(v_right - v_left))
+
+
+def _tonry_davis_r(ccf: np.ndarray, ipeak: int, peak_height: float) -> float | None:
+    """Tonry & Davis 1979 r = h / (√2 · σ_a).
+
+    σ_a is the RMS of the antisymmetric component
+    ``a(δ) = [ccf(peak+δ) − ccf(peak−δ)] / 2`` measured **away from
+    the peak**, where the signal is dominated by noise. The window
+    used here is the outer half of the CCF (the inner half is the
+    peak itself).
+    """
+    if peak_height <= 0.0:
+        return None
+    n = ccf.size
+    if n < 16:
+        return None
+    # Symmetric δ range around the peak — capped to whichever side of
+    # the peak is shorter, so we never index past either end.
+    half_span = min(ipeak, n - 1 - ipeak)
+    if half_span < 4:
+        return None
+    deltas = np.arange(1, half_span + 1)
+    left = ccf[ipeak - deltas]
+    right = ccf[ipeak + deltas]
+    antisym = 0.5 * (right - left)
+    # Far-from-peak window for the noise estimate (outer 50 %).
+    tail_start = half_span // 2
+    tail = antisym[tail_start:]
+    if tail.size < 4:
+        return None
+    sigma_a = float(np.sqrt(np.mean(tail ** 2)))
+    if sigma_a <= 0.0:
+        return None
+    return float(peak_height / (math.sqrt(2.0) * sigma_a))
+
+
+def _template_identifier(params: dict[str, Any]) -> str | None:
+    """Best-effort label for the template used (path basename or extras key)."""
+    if params.get("template_path"):
+        return os.path.basename(str(params["template_path"]))
+    if params.get("template_key"):
+        return str(params["template_key"])
+    return None
+
+
+@register_algorithm(
+    "cross_correlate_rv",
+    category=AlgorithmCategory.RADIAL_VELOCITY,
+    # 1.2.0: add peak_strength, Tonry-Davis r-value error, extras.ccf, extras.template_id.
+    version="1.2.0",
+)
+class CrossCorrelateRv(BaseAlgorithm):
+    """Measure radial velocity by cross-correlation against a template spectrum.
+
+    Both spectra are resampled to a common log-wavelength grid (so a
+    shift in samples maps to a constant velocity); their normalised
+    cross-correlation function (CCF) is computed; the peak is located
+    with sub-pixel parabolic refinement; the shift converts to
+    velocity via ``v = c · dln(λ)``.
+
+    Outputs (v1.2.0) :
+
+    - ``metrics.radial_velocity_kms`` — RV in km/s (positive = redshifted
+      vs. template).
+    - ``metrics.radial_velocity_error_kms`` — Tonry & Davis 1979 §III
+      error : ``σ_v = 3 · w / (8 · (1 + r))`` with ``w`` = peak FWHM
+      and ``r = h / (√2 · σ_a)``. ``NaN`` if the CCF shape forbids the
+      estimate (no resolved peak, no antisymmetric noise sample).
+    - ``metrics.peak_strength`` — Pearson-normalised peak height in
+      ``[0, 1]``. 1 ⇒ template-identical observed spectrum.
+    - ``extras.ccf`` — ``{"lags_kms": [...], "ccf": [...]}``, the CCF
+      curve restricted to the velocity search window.
+    - ``extras.template_id`` — best-effort label of the template used
+      (file basename or ``ctx.extras`` key).
+    """
+
+    backend = "scipy"
+    references = [
+        "Tonry & Davis 1979, AJ 84, 1511 — fundamental CCF method for "
+        "RV ; r-value and σ_v = 3·w/(8·(1+r)) error formula (§III).",
+        "scipy.signal.correlate — cross-correlation engine.",
+    ]
+    long_description = (
+        "Template comes from `template_path` (FITS), `template_key` (a "
+        "Spectrum1D under ctx.extras), `ctx.extras['template_spectrum']` "
+        "or `ctx.spectra[0]` — first match wins. Both spectra are "
+        "centred (mean = 0) before correlation, so the reported "
+        "peak_strength is bounded in [0, 1]. The RV error is the "
+        "Tonry-Davis 1979 formula ; it underestimates the true error "
+        "for asymmetric CCFs (multi-component blended templates) — use "
+        "MCMC / bootstrap if higher fidelity is needed."
+    )
+    default_params = {
+        "template_path": None,
+        "template_key": None,
+        "n_grid": 4096,
+        "vmin_kms": -800.0,
+        "vmax_kms": 800.0,
+    }
+    param_descriptions = {
+        "template_path": "Path / URL of a template FITS spectrum to load.",
+        "template_key": "Key in ctx.extras where a Spectrum1D template is stored.",
+        "n_grid": "Number of log-wavelength samples on which to interpolate.",
+        "vmin_kms": "Lower bound of the velocity search range (km/s).",
+        "vmax_kms": "Upper bound of the velocity search range (km/s).",
+    }
+    input_requirements = ["spectrum"]
+    output_produces = [
+        "metrics.radial_velocity_kms",
+        "metrics.radial_velocity_error_kms",
+        "metrics.peak_strength",
+        "extras.ccf",
+        "extras.template_id",
+    ]
+
+    def run(self, ctx: WorkContext, params: dict[str, Any]) -> AlgorithmOutput:
+        spec = ctx.spectrum
+        template = self._resolve_template(ctx, params)
+        if template is None:
+            return AlgorithmOutput.fail(
+                "No template available — pass template_path, set "
+                "ctx.extras['template_spectrum'], or put one in ctx.spectra[0]."
+            )
+
+        wmin = max(spec.wavelength_min, template.wavelength_min)
+        wmax = min(spec.wavelength_max, template.wavelength_max)
+        if wmin >= wmax:
+            return AlgorithmOutput.fail(
+                "Spectrum and template do not overlap in wavelength."
+            )
+
+        n = int(params["n_grid"])
+        log_grid = np.linspace(np.log(wmin), np.log(wmax), n)
+        delta_log = (log_grid[-1] - log_grid[0]) / (n - 1)
+        wave_grid = np.exp(log_grid)
+
+        # np.interp does NOT skip NaN samples — a single bad pixel in
+        # the input poisons the whole row. Strip NaNs before interpolating.
+        spec_f = _interp_skip_nan(wave_grid, spec.wavelength, spec.flux)
+        templ_f = _interp_skip_nan(wave_grid, template.wavelength, template.flux)
+        # Centre both signals so the CCF is bounded in [-1, 1] after
+        # Pearson normalisation below.
+        spec_f = spec_f - float(np.nanmean(spec_f))
+        templ_f = templ_f - float(np.nanmean(templ_f))
+
+        # Pearson normalisation : ccf_norm ∈ [-1, 1] regardless of
+        # absolute scale. The CCF peak then directly reads as a
+        # similarity score, suitable for a UI confidence indicator.
+        spec_norm = float(np.sqrt(np.sum(spec_f * spec_f)))
+        templ_norm = float(np.sqrt(np.sum(templ_f * templ_f)))
+        if spec_norm <= 0.0 or templ_norm <= 0.0:
+            return AlgorithmOutput.fail(
+                "Observed or template signal vanishes after centring — "
+                "check input is not flat."
+            )
+        ccf = correlate(spec_f, templ_f, mode="full") / (spec_norm * templ_norm)
+        lags = np.arange(-(n - 1), n, dtype=np.float64)
+        velocities = lags * delta_log * _C_KMS
+
+        vmin = float(params["vmin_kms"])
+        vmax = float(params["vmax_kms"])
+        window = (velocities >= vmin) & (velocities <= vmax)
+        if not window.any():
+            return AlgorithmOutput.fail(
+                "Velocity search range too narrow given n_grid."
+            )
+        ccf_w = ccf[window]
+        v_w = velocities[window]
+
+        ipeak = int(np.argmax(ccf_w))
+        v_peak = float(v_w[ipeak])
+        peak_height = float(ccf_w[ipeak])
+        # Parabolic vertex refinement (sub-velocity-bin precision).
+        if 0 < ipeak < ccf_w.size - 1:
+            y0, y1, y2 = ccf_w[ipeak - 1], ccf_w[ipeak], ccf_w[ipeak + 1]
+            denom = y0 - 2.0 * y1 + y2
+            if denom != 0.0:
+                offset = 0.5 * (y0 - y2) / denom
+                v_peak += float(offset) * float(v_w[1] - v_w[0])
+
+        # peak_strength: clamp to [0, 1] for the UI confidence indicator
+        # (negative peaks would mean anti-correlation, which the consumer
+        # treats as "no match").
+        peak_strength = float(max(0.0, min(1.0, peak_height)))
+
+        # RV error — Tonry & Davis 1979 §III: σ_v = 3·w / (8·(1+r)).
+        fwhm_kms = _peak_fwhm_kms(v_w, ccf_w, ipeak)
+        r_value = _tonry_davis_r(ccf_w, ipeak, peak_height)
+        if fwhm_kms is not None and r_value is not None and (1.0 + r_value) > 0.0:
+            rv_error_kms: float = _TD_ERROR_COEF * fwhm_kms / (1.0 + r_value)
+        else:
+            rv_error_kms = float("nan")
+
+        template_id = _template_identifier(params)
+
+        ctx.metrics["radial_velocity_kms"] = v_peak
+        ctx.metrics["radial_velocity_error_kms"] = rv_error_kms
+        ctx.metrics["peak_strength"] = peak_strength
+        ctx.extras["ccf"] = {
+            "lags_kms": v_w.tolist(),
+            "ccf": ccf_w.tolist(),
+        }
+        if template_id is not None:
+            ctx.extras["template_id"] = template_id
+
+        metrics_out: dict[str, float] = {
+            "radial_velocity_kms": v_peak,
+            "radial_velocity_error_kms": rv_error_kms,
+            "peak_strength": peak_strength,
+            "ccf_peak": peak_height,
+        }
+        if r_value is not None:
+            metrics_out["tonry_davis_r"] = float(r_value)
+        if fwhm_kms is not None:
+            metrics_out["ccf_fwhm_kms"] = float(fwhm_kms)
+
+        message_bits = [f"RV = {v_peak:+.2f} km/s"]
+        if not math.isnan(rv_error_kms):
+            message_bits.append(f"± {rv_error_kms:.2f} km/s")
+        message_bits.append(f"peak strength = {peak_strength:.3f}")
+        if template_id:
+            message_bits.append(f"template = {template_id}")
+        message = ", ".join(message_bits) + "."
+
+        return AlgorithmOutput.ok(
+            metrics=metrics_out,
+            artifacts={
+                "velocity_kms": v_w.tolist(),
+                "ccf": ccf_w.tolist(),
+                "template_id": template_id,
+            },
+            message=message,
+        )
+
+    @staticmethod
+    def _resolve_template(ctx: WorkContext, params: dict[str, Any]) -> Spectrum1D | None:
+        if params["template_path"]:
+            return read_fits(params["template_path"])
+        if params["template_key"]:
+            value = ctx.extras.get(params["template_key"])
+            if isinstance(value, Spectrum1D):
+                return value
+        value = ctx.extras.get("template_spectrum")
+        if isinstance(value, Spectrum1D):
+            return value
+        if ctx.spectra:
+            return ctx.spectra[0]
+        return None
+
+
+def _interp_skip_nan(x_new: np.ndarray, xp: np.ndarray, fp: np.ndarray) -> np.ndarray:
+    """Linear interp that ignores NaN samples in ``fp``.
+
+    ``np.interp`` happily extrapolates a NaN through every sample whose
+    neighbouring source point is NaN; for cross-correlation that means a
+    single bad pixel destroys the CCF. Stripping NaNs first preserves the
+    rest of the signal at the cost of a slightly biased local interpolation.
+    """
+    finite = np.isfinite(fp)
+    if finite.all():
+        return np.interp(x_new, xp, fp)
+    if not finite.any():
+        return np.zeros_like(x_new)
+    return np.interp(x_new, xp[finite], fp[finite])

{spectro_kernel-0.4.0 → spectro_kernel-0.4.1}/src/spectro_kernel/version.py

@@ -1,3 +1,3 @@
 """Single source of truth for the package version."""
 
-__version__ = "0.4.0"
+__version__ = "0.4.1"

spectro_kernel-0.4.1/tests/unit/test_cross_correlate_extension.py

@@ -0,0 +1,118 @@
+"""Tests for the v1.2.0 cross_correlate_rv extensions.
+
+The v1.1.0 RV-recovery behaviour is exercised in
+``tests/reference/test_known_answers.py`` ; here we exercise the
+**new outputs** : peak_strength, Tonry-Davis r-value error, ccf
+artefact, and template_id provenance.
+"""
+
+from __future__ import annotations
+
+import math
+
+import numpy as np
+
+from spectro_kernel import WorkContext, run_algorithm
+from spectro_kernel.types import Spectrum1D
+
+
+def _template(seed: int = 0, npix: int = 2000) -> Spectrum1D:
+    """A template-like spectrum: smooth continuum + a few absorption dips."""
+    rng = np.random.default_rng(seed)
+    wave = np.linspace(5000.0, 6000.0, npix)
+    flux = 100.0 + rng.normal(0.0, 0.3, npix)
+    for centre in (5172.0, 5183.6, 5400.0, 5600.0, 5890.0):
+        flux -= 30.0 * np.exp(-0.5 * ((wave - centre) / 1.5) ** 2)
+    return Spectrum1D(wavelength=wave, flux=flux, wavelength_unit="Angstrom")
+
+
+def _doppler_shifted(template: Spectrum1D, v_kms: float) -> Spectrum1D:
+    c = 299_792.458
+    shifted_wave = template.wavelength * (1.0 + v_kms / c)
+    return Spectrum1D(wavelength=shifted_wave, flux=template.flux.copy())
+
+
+def test_peak_strength_is_near_unity_for_self_correlation():
+    """Spec = template (v = 0) ⇒ peak_strength ≈ 1, error small."""
+    tmpl = _template()
+    ctx = WorkContext(spectrum=Spectrum1D(wavelength=tmpl.wavelength, flux=tmpl.flux))
+    ctx.extras["template_spectrum"] = tmpl
+    out = run_algorithm("cross_correlate_rv", ctx, {"n_grid": 4096})
+    assert out.success
+    assert abs(ctx.metrics["radial_velocity_kms"]) < 2.0
+    assert ctx.metrics["peak_strength"] > 0.95
+    assert ctx.metrics["peak_strength"] <= 1.0
+    # Error finite, small for a self-correlation.
+    err = ctx.metrics["radial_velocity_error_kms"]
+    assert math.isfinite(err)
+    assert err < 10.0
+
+
+def test_peak_strength_and_error_present_for_shifted_input():
+    """Shifted by +120 km/s ⇒ RV ≈ 120, peak_strength ∈ ]0, 1], error > 0."""
+    tmpl = _template()
+    obs = _doppler_shifted(tmpl, +120.0)
+    ctx = WorkContext(spectrum=obs)
+    ctx.extras["template_spectrum"] = tmpl
+    out = run_algorithm("cross_correlate_rv", ctx, {"n_grid": 4096})
+    assert out.success
+    assert abs(ctx.metrics["radial_velocity_kms"] - 120.0) < 2.0
+    ps = ctx.metrics["peak_strength"]
+    assert 0.0 < ps <= 1.0
+    assert ctx.metrics["radial_velocity_error_kms"] > 0.0
+
+
+def test_ccf_artefact_is_exposed_in_extras():
+    """extras['ccf'] = {lags_kms, ccf} for downstream plotting."""
+    tmpl = _template()
+    ctx = WorkContext(spectrum=_doppler_shifted(tmpl, 50.0))
+    ctx.extras["template_spectrum"] = tmpl
+    out = run_algorithm("cross_correlate_rv", ctx, {"n_grid": 2048})
+    assert out.success
+    ccf = ctx.extras["ccf"]
+    assert set(ccf.keys()) == {"lags_kms", "ccf"}
+    assert len(ccf["lags_kms"]) == len(ccf["ccf"])
+    assert len(ccf["lags_kms"]) > 10
+    # The CCF peak in extras should align with the reported RV (within
+    # one velocity-bin given the parabolic refinement).
+    lags = np.asarray(ccf["lags_kms"])
+    values = np.asarray(ccf["ccf"])
+    v_peak_bin = float(lags[int(np.argmax(values))])
+    assert abs(v_peak_bin - ctx.metrics["radial_velocity_kms"]) < (lags[1] - lags[0]) + 1e-9
+
+
+def test_template_id_is_extracted_from_template_key():
+    """When the user passes template_key, extras['template_id'] echoes it."""
+    tmpl = _template()
+    ctx = WorkContext(spectrum=_doppler_shifted(tmpl, 0.0))
+    ctx.extras["my_template"] = tmpl
+    out = run_algorithm(
+        "cross_correlate_rv", ctx,
+        {"template_key": "my_template", "n_grid": 2048},
+    )
+    assert out.success
+    assert ctx.extras["template_id"] == "my_template"
+
+
+def test_failure_on_no_template_keeps_pre_v1_2_0_contract():
+    spec = _template()
+    ctx = WorkContext(spectrum=spec)
+    out = run_algorithm("cross_correlate_rv", ctx, raise_on_error=False)
+    assert not out.success
+    assert "template" in (out.error or "").lower()
+
+
+def test_failure_on_zero_wavelength_overlap_is_clear():
+    tmpl = Spectrum1D(
+        wavelength=np.linspace(5000.0, 5500.0, 1000),
+        flux=np.ones(1000),
+    )
+    obs = Spectrum1D(
+        wavelength=np.linspace(6000.0, 6500.0, 1000),
+        flux=np.ones(1000),
+    )
+    ctx = WorkContext(spectrum=obs)
+    ctx.extras["template_spectrum"] = tmpl
+    out = run_algorithm("cross_correlate_rv", ctx, raise_on_error=False)
+    assert not out.success
+    assert "overlap" in (out.error or "").lower()

spectro_kernel-0.4.0/src/spectro_kernel/algorithms/rv/cross_correlate.py

@@ -1,151 +0,0 @@
-"""Algorithm: cross-correlate against a template to measure radial velocity."""
-
-from __future__ import annotations
-
-from typing import Any
-
-import astropy.constants as const
-import astropy.units as u
-import numpy as np
-from scipy.signal import correlate
-
-from ...base import AlgorithmOutput, BaseAlgorithm
-from ...io import read_fits
-from ...registry import register_algorithm
-from ...types import AlgorithmCategory, Spectrum1D, WorkContext
-
-_C_KMS = const.c.to(u.km / u.s).value
-
-
-@register_algorithm(
-    "cross_correlate_rv",
-    category=AlgorithmCategory.RADIAL_VELOCITY,
-    version="1.1.0",   # 1.1.0: strip NaN samples before np.interp (no NaN propagation)
-)
-class CrossCorrelateRv(BaseAlgorithm):
-    """Measure radial velocity by cross-correlation against a template spectrum.
-
-    Both spectra are resampled to a common log-wavelength grid (so a shift in samples
-    maps to a constant velocity); their cross-correlation function (CCF) is computed;
-    the peak is located with sub-pixel parabolic refinement; the shift converts to
-    velocity via ``v = c * dln(lambda)``.
-    """
-
-    backend = "scipy"
-    references = [
-        "Tonry & Davis 1979, AJ 84, 1511 — fundamental CCF method for RV",
-        "scipy.signal.correlate",
-    ]
-    long_description = (
-        "Provide the template either as a file (`template_path`), a key into "
-        "ctx.extras (`template_key`), or fall back to `ctx.spectra[0]`. The reported "
-        "velocity is positive when the science spectrum is redshifted vs. the template."
-    )
-    default_params = {
-        "template_path": None,
-        "template_key": None,
-        "n_grid": 4096,
-        "vmin_kms": -800.0,
-        "vmax_kms": 800.0,
-    }
-    param_descriptions = {
-        "template_path": "Path / URL of a template FITS spectrum to load.",
-        "template_key": "Key in ctx.extras where a Spectrum1D template is stored.",
-        "n_grid": "Number of log-wavelength samples on which to interpolate.",
-        "vmin_kms": "Lower bound of the velocity search range (km/s).",
-        "vmax_kms": "Upper bound of the velocity search range (km/s).",
-    }
-    input_requirements = ["spectrum"]
-    output_produces = ["metrics.radial_velocity_kms"]
-
-    def run(self, ctx: WorkContext, params: dict[str, Any]) -> AlgorithmOutput:
-        spec = ctx.spectrum
-        template = self._resolve_template(ctx, params)
-        if template is None:
-            return AlgorithmOutput.fail(
-                "No template available — pass template_path, set ctx.extras['template_spectrum'], "
-                "or put one in ctx.spectra[0]."
-            )
-
-        wmin = max(spec.wavelength_min, template.wavelength_min)
-        wmax = min(spec.wavelength_max, template.wavelength_max)
-        if wmin >= wmax:
-            return AlgorithmOutput.fail("Spectrum and template do not overlap in wavelength.")
-
-        n = int(params["n_grid"])
-        log_grid = np.linspace(np.log(wmin), np.log(wmax), n)
-        delta_log = (log_grid[-1] - log_grid[0]) / (n - 1)
-        wave_grid = np.exp(log_grid)
-
-        # np.interp does NOT skip NaN samples — a single bad pixel in the
-        # input poisons the whole row. Strip NaNs before interpolating.
-        spec_f = _interp_skip_nan(wave_grid, spec.wavelength, spec.flux)
-        templ_f = _interp_skip_nan(wave_grid, template.wavelength, template.flux)
-        # Centre both signals so the CCF is comparable across spectra.
-        spec_f = spec_f - float(np.nanmean(spec_f))
-        templ_f = templ_f - float(np.nanmean(templ_f))
-
-        ccf = correlate(spec_f, templ_f, mode="full")
-        lags = np.arange(-(n - 1), n, dtype=np.float64)
-        velocities = lags * delta_log * _C_KMS
-
-        vmin = float(params["vmin_kms"])
-        vmax = float(params["vmax_kms"])
-        window = (velocities >= vmin) & (velocities <= vmax)
-        if not window.any():
-            return AlgorithmOutput.fail("Velocity search range too narrow given n_grid.")
-        ccf_w = ccf[window]
-        v_w = velocities[window]
-
-        ipeak = int(np.argmax(ccf_w))
-        v_peak = float(v_w[ipeak])
-        # Parabolic vertex refinement (sub-velocity-bin precision).
-        if 0 < ipeak < ccf_w.size - 1:
-            y0, y1, y2 = ccf_w[ipeak - 1], ccf_w[ipeak], ccf_w[ipeak + 1]
-            denom = y0 - 2.0 * y1 + y2
-            if denom != 0.0:
-                offset = 0.5 * (y0 - y2) / denom
-                v_peak += float(offset) * float(v_w[1] - v_w[0])
-
-        ctx.metrics["radial_velocity_kms"] = v_peak
-        return AlgorithmOutput.ok(
-            metrics={"radial_velocity_kms": v_peak, "ccf_peak": float(ccf_w[ipeak])},
-            artifacts={
-                "velocity_kms": v_w.tolist(),
-                "ccf": ccf_w.tolist(),
-            },
-            message=f"Cross-correlation RV = {v_peak:+.2f} km/s",
-        )
-
-    @staticmethod
-    def _resolve_template(ctx: WorkContext, params: dict[str, Any]) -> Spectrum1D | None:
-        if params["template_path"]:
-            return read_fits(params["template_path"])
-        if params["template_key"]:
-            value = ctx.extras.get(params["template_key"])
-            if isinstance(value, Spectrum1D):
-                return value
-        value = ctx.extras.get("template_spectrum")
-        if isinstance(value, Spectrum1D):
-            return value
-        if ctx.spectra:
-            return ctx.spectra[0]
-        return None
-
-
-def _interp_skip_nan(x_new: np.ndarray, xp: np.ndarray, fp: np.ndarray) -> np.ndarray:
-    """Linear interp that ignores NaN samples in ``fp``.
-
-    ``np.interp`` happily extrapolates a NaN through every sample whose
-    neighbouring source point is NaN; for cross-correlation that means a
-    single bad pixel destroys the CCF. Stripping NaNs first preserves the
-    rest of the signal at the cost of a slightly biased local interpolation.
-    """
-    finite = np.isfinite(fp)
-    if finite.all():
-        return np.interp(x_new, xp, fp)
-    if not finite.any():
-        return np.zeros_like(x_new)
-    return np.interp(x_new, xp[finite], fp[finite])
-
-