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

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

@@ -6,6 +6,160 @@ 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
+dashboard's needs (STAROS, see `stuff/spectro_kernel_spec_25_06_26.md`).
+Adds **8 new algorithms across 3 new categories** (`nebular`,
+`kinematics`, `classification`), extends `detect_lines` with a
+blind mode (no catalogue identification), and factors a shared
+Gaussian-line-flux primitive used by the nebular diagnostics.
+
+Each new brick cites the literature paper that defines its formula
+(no fabricated references) and reproduces the published coefficients
+verbatim in code.
+
+### Added — nebular diagnostics (3 algorithms)
+
+- **`oiii_electron_temperature`** (category `nebular`) — electron
+  temperature Te from the [O III] λ4363/λ5007 auroral-to-nebular
+  ratio. Implements the 5-level inversion of **Aller 1984**
+  (*Physics of Thermal Gaseous Nebulae*), as derived in
+  **Osterbrock & Ferland 2006** §5.6 :
+  ``Te = 32900 / ln(R / 7.90)``. Valid for ``n_e ≲ 10⁵ cm⁻³`` and
+  ``Te ∈ [3000, 30000] K`` ; outside that range the algorithm reports
+  ``te_kelvin = NaN`` and tags the regime in ``extras["regime"]``.
+- **`sii_electron_density`** (category `nebular`) — electron density
+  n_e from the [S II] λ6716/λ6731 ratio. Uses the polynomial-plus-arctan
+  fit of **Proxauf, Öttl & Kimeswenger 2014** (A&A 561, A10, Eq. 6,
+  coefficients copied verbatim) at Te ≈ 10⁴ K for
+  ``0.45 ≲ R ≲ 1.43`` ; saturates cleanly at the low- and
+  high-density limits with explicit regime labelling.
+- **`bpt_line_ratios`** (category `nebular`) — measures the 4
+  standard BPT log-ratios and classifies a galaxy as
+  ``HII / Composite / Seyfert / LINER`` in the [N II]/Hα plane.
+  Demarcations from **Kauffmann et al. 2003** (MNRAS 346, 1055),
+  **Kewley & Dopita 2001** (ApJ 556, 121) and **Cid Fernandes
+  et al. 2010** (MNRAS 403, 1036) ; origin paper **Baldwin, Phillips
+  & Terlevich 1981** (PASP 93, 5).
+
+### Added — binary / variable diagnostics (2 algorithms)
+
+- **`vr_ratio`** (category `line_fitting`) — Violet/Red intensity
+  ratio of a double-peaked emission line, the standard asymmetry
+  diagnostic for Be-star circumstellar discs (Hα by default) and
+  any other source with a resolved double profile (symbiotic stars,
+  novae, AGN BLR). Theory grounding : **Okazaki 1991** (A&A 246,
+  415, one-armed density waves), **Hummel & Vrancken 2000** (A&A
+  359, 1075). Detection via ``scipy.signal.find_peaks`` on the
+  edge-continuum-normalised window.
+- **`doppler_tomogram`** (category `advanced`) — Doppler tomography
+  of a binary system by **Marsh & Horne 1988** (MNRAS 235, 269) §2
+  back-projection. Reconstructs the brightness distribution
+  ``I(V_x, V_y)`` from N phase-resolved spectra of a known-period
+  binary. NaN-aware averaging of the per-phase contributions keeps
+  the phase-coverage footprint out of the brightness map.
+  Complements the existing ``disentangle_sb2`` ; MEM (Horne 1985)
+  is left to a future v2.
+
+### Added — extragalactic kinematics (2 algorithms)
+
+- **`redshift_lines`** (category `radial_velocity`) — redshift z by
+  per-line Gaussian fits against a list of anchor lines (SDSS
+  spec1d style, **Stoughton et al. 2002** AJ 123, 485) ; default
+  list = 9 strong galaxy lines ([O II], Ca II H+K, Hβ, [O III],
+  Mg b, Na D, Hα, [N II]). Tries emission + absorption fits and
+  keeps the lower residual, so the same brick covers
+  emission-line galaxies and quiescent absorption-line systems.
+- **`rotation_curve`** (category **kinematics**, new) — projected
+  long-slit rotation curve ``v_los(r)`` from per-spectrum Hα fits
+  indexed by slit offset (arcsec from galactic centre). Origin :
+  **Rubin et al. 1980** (ApJ 238, 471), reviewed in **Sofue &
+  Rubin 2001** (ARA&A 39, 137). Simple projection only — no
+  inclination correction, no asymmetric drift, no 2-D modelling.
+
+### Added — spectral classification (1 algorithm + atlas loader)
+
+- **`classify_template_chi2`** (category **classification**, new) —
+  spectral type by unweighted χ² against a Pickles-style template
+  atlas (**Pickles 1998**, PASP 110, 863). Returns top-N matches
+  plus confidence flags (``ambiguous`` = χ²[1]/χ²[0] < 1.20 ;
+  ``teff_unstable`` = top-3 ``ΔT_eff`` > 500 K). The atlas itself
+  is **not bundled** (≈ 1 MB of data, redistribution OK with
+  attribution but kept out of the thin core install) ; a loader
+  helper :mod:`spectro_kernel.algorithms.classification.pickles_atlas`
+  reads the downloadable ASCII templates from ESO
+  (``ftp.eso.org/pub/stecf/standards/hststan/uvklib/``) or VizieR
+  (``J/PASP/110/863/``) into the algorithm's expected
+  :class:`Atlas` shape.
+
+### Added — blind line detection (extension)
+
+- **`detect_lines`** v1.1.0 → **v1.2.0**: a new ``catalog=None``
+  mode runs a blind detection (no catalogue identification) and
+  emits a richer schema per line (continuum, signed amplitude, SNR,
+  FWHM, prominence) plus the MAD-robust noise level
+  (``1.4826 · MAD``, Hampel 1974) used for the prominence
+  threshold. The v1.1.0 catalogue mode is preserved bit-exact.
+
+### Added — shared primitive
+
+- **`spectro_kernel.algorithms.lines._line_flux.gaussian_line_flux`** —
+  factored "Gaussian + local continuum" fit used by the three
+  nebular bricks. Window-edge continuum (median of the two outer
+  bands), ``curve_fit`` with seeds, analytic flux
+  ``F = |amp| · |σ| · √(2π)``. Returns ``None`` on bad fits so
+  callers can degrade gracefully.
+
+### Added — new categories
+
+`AlgorithmCategory` gains `NEBULAR`, `KINEMATICS` and
+`CLASSIFICATION` for the new specialised domains.
+``docs/gen_catalogue.py`` gets matching titles so the catalogue
+page renders them as *Nebular diagnostics*, *Kinematics* and
+*Spectral classification*.
+
+### Numbers
+
+**113 algorithms** registered (was 105). 325 tests pass (32 new),
+ruff clean, mkdocs strict OK.
+
 ## [0.3.0] — 2026-06-09
 
 A focused expansion driven by the LineMill stellar-spectroscopy work

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spectro-kernel
-Version: 0.3.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.3.0 → spectro_kernel-0.4.1}/docs/gen_catalogue.py

@@ -30,6 +30,9 @@ _CATEGORY_TITLES = {
     "timeseries": "Time series",
     "stacking": "Stacking",
     "embedding": "Embeddings",
+    "nebular": "Nebular diagnostics",
+    "kinematics": "Kinematics",
+    "classification": "Spectral classification",
     "catalog": "External catalogues",
     "visualization": "Visualisation",
     "export": "Export",

spectro_kernel-0.4.1/src/spectro_kernel/algorithms/advanced/doppler_tomogram.py

@@ -0,0 +1,311 @@
+"""Algorithm: Doppler tomography by back-projection (Marsh & Horne 1988).
+
+Given N phase-resolved spectra of a known-period binary system, this
+brick reconstructs the **brightness distribution in the velocity space
+of the binary** ``I(V_x, V_y)`` by simple **back-projection** — the
+direct inversion of the trailed-spectrogram → velocity-map mapping
+established by Marsh & Horne 1988.
+
+Mathematical model (§2 of Marsh & Horne 1988) :
+
+For each spectrum taken at orbital phase ``φ ∈ [0, 1)``, the line
+profile records the integral of ``I(V_x, V_y)`` along all lines of
+sight projected onto the radial velocity
+
+    v(φ; V_x, V_y) = γ − V_x · sin(2π φ) + V_y · cos(2π φ)         (Eq. 1)
+
+where ``γ`` is the binary's systemic velocity. The back-projection
+estimator inverts Eq. 1 by smearing each phase-spectrum along its own
+sinusoidal locus in the ``(V_x, V_y)`` plane :
+
+    M(V_x, V_y) ≈ ⟨ I_φ(γ − V_x · sin 2πφ + V_y · cos 2πφ) ⟩_φ    (Eq. 2)
+
+where ``⟨·⟩_φ`` averages over phases that *contribute* to each
+``(V_x, V_y)`` pixel (NaN-aware mean — pixels with no contributing
+phase are reported as ``0``, not ``NaN/0``).
+
+Back-projection is the simplest tomographic reconstruction; **Maximum
+Entropy Method (MEM)** (Horne 1985) is a more advanced alternative
+that suppresses the streak artefacts of pure back-projection. MEM is
+intentionally left out of v1.0.0 to keep the surface tight.
+
+Phase computation : ``φ = ((JD_mid − epoch_HJD) / period) mod 1``.
+Each input ``Spectrum1D`` must carry its **mid-exposure JD** in
+``spec.meta["jd_mid"]`` ; if absent, the algorithm falls back to
+deriving it from ``spec.meta["dateobs"]`` and ``spec.meta["exptime_s"]``
+(``jd_mid = Time(dateobs).jd + exptime_s / 2 / 86400``), which requires
+``astropy.time`` (imported lazily).
+
+References
+----------
+- **Marsh & Horne 1988**, MNRAS 235, 269 — *Images of accretion discs.
+  II. Doppler tomography* (the canonical back-projection paper).
+- **Horne 1985**, MNRAS 213, 129 — MEM tomographic reconstruction
+  (not implemented; cited for completeness).
+- **Marsh 2001**, *Astrotomography*, Lecture Notes in Physics 573 —
+  modern review (back-projection vs MEM vs χ² + regularised MEM).
+"""
+
+from __future__ import annotations
+
+import math
+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, Spectrum1D, WorkContext
+
+_SPEED_OF_LIGHT_KMS: float = 299792.458
+
+
+def _resolve_jd_mid(spec: Spectrum1D) -> float | None:
+    """Extract or derive the mid-exposure JD from the spectrum's meta."""
+    if spec.meta is None:
+        return None
+    jd_mid = spec.meta.get("jd_mid")
+    if jd_mid is not None:
+        return float(jd_mid)
+    dateobs = spec.meta.get("dateobs")
+    exptime = spec.meta.get("exptime_s")
+    if dateobs is None or exptime is None:
+        return None
+    try:
+        from astropy.time import Time  # noqa: PLC0415 - astropy is heavy
+    except ImportError:
+        return None
+    try:
+        return float(Time(dateobs).jd + float(exptime) / 2.0 / 86400.0)
+    except Exception:  # noqa: BLE001 - astropy raises a variety of types
+        return None
+
+
+def _line_excess_on_velocity_grid(
+    spec: Spectrum1D, line_centre_aa: float, velocity_grid: np.ndarray,
+) -> np.ndarray | None:
+    """Resample the spectrum onto a velocity grid and subtract the continuum.
+
+    Returns ``intensity − 1`` (the line excess above unit continuum) or
+    ``None`` if the input is too short / continuum non-positive.
+    """
+    wave = np.asarray(spec.wavelength, dtype=np.float64)
+    flux = np.asarray(spec.flux, dtype=np.float64)
+    finite = np.isfinite(wave) & np.isfinite(flux)
+    if int(finite.sum()) < 30:
+        return None
+    wave = wave[finite]
+    flux = flux[finite]
+    velocity = _SPEED_OF_LIGHT_KMS * (wave - line_centre_aa) / line_centre_aa
+    intensity = np.interp(velocity_grid, velocity, flux, left=np.nan, right=np.nan)
+    n_edge = max(5, int(0.1 * intensity.size))
+    finite_int = np.isfinite(intensity)
+    if int(finite_int.sum()) < n_edge * 2:
+        return None
+    head_edge = intensity[finite_int][:n_edge]
+    tail_edge = intensity[finite_int][-n_edge:]
+    continuum = 0.5 * (float(np.median(head_edge)) + float(np.median(tail_edge)))
+    if continuum <= 0.0:
+        return None
+    return intensity / continuum - 1.0
+
+
+def _back_project(
+    trailed: np.ndarray,             # (n_phases, n_velocity)
+    phases: np.ndarray,              # (n_phases,)
+    velocity_grid: np.ndarray,       # (n_velocity,)
+    gamma_kms: float,
+    n_velocity: int,
+) -> np.ndarray:
+    """Back-project the trailed spectrogram into the (V_x, V_y) plane."""
+    VX, VY = np.meshgrid(velocity_grid, velocity_grid, indexing="xy")
+    accumulator = np.zeros_like(VX, dtype=np.float64)
+    n_contrib = np.zeros_like(VX, dtype=np.float64)
+
+    for phase, row in zip(phases, trailed, strict=True):
+        phi = 2.0 * math.pi * float(phase)
+        v_proj = gamma_kms - VX * math.sin(phi) + VY * math.cos(phi)
+        # Resample the row onto v_proj; pixels with v_proj outside the
+        # velocity grid get NaN and are masked out of the average.
+        flat = np.interp(
+            v_proj.ravel(),
+            velocity_grid,
+            row,
+            left=np.nan,
+            right=np.nan,
+        ).reshape(VX.shape)
+        valid = np.isfinite(flat)
+        accumulator[valid] += flat[valid]
+        n_contrib[valid] += 1.0
+
+    with np.errstate(invalid="ignore"):
+        out = np.where(n_contrib > 0.0, accumulator / n_contrib, 0.0)
+    return out
+
+
+@register_algorithm(
+    "doppler_tomogram",
+    category=AlgorithmCategory.ADVANCED,
+    version="1.0.0",
+)
+class DopplerTomogram(BaseAlgorithm):
+    """Doppler tomogram of a binary from N phase-resolved spectra.
+
+    Composes ``ctx.spectra`` (N ``Spectrum1D``, one per orbital phase)
+    into the ``(V_x, V_y)`` brightness map ``M`` by Marsh & Horne 1988
+    back-projection. Each input spectrum **must** carry its
+    mid-exposure timestamp in one of :
+
+    - ``spec.meta["jd_mid"]`` (preferred, no astropy dependency), OR
+    - ``spec.meta["dateobs"]`` + ``spec.meta["exptime_s"]`` (computed
+      with ``astropy.time.Time``).
+
+    Sits next to ``disentangle_sb2`` in the ``advanced`` category :
+    they share the binary-system focus but solve different problems —
+    disentangling produces two 1-D component spectra ; tomography
+    produces one 2-D velocity-space brightness map.
+
+    Outputs (under ``ctx.extras["tomography_result"]``) :
+
+    - ``velocity_grid_kms`` : (n_velocity,) symmetric grid.
+    - ``phase_grid`` : (n_spectra,) sorted phases.
+    - ``trailed_spectrogram`` : (n_phases, n_velocity) input intensity.
+    - ``doppler_map`` : (n_velocity, n_velocity) reconstructed M.
+
+    Companion bricks one could build later : ``doppler_tomogram_mem``
+    (Horne 1985) for sharper reconstructions, and a ``trailed_spectrum_view``
+    visualisation.
+    """
+
+    backend = "numpy"
+    references = [
+        "Marsh & Horne 1988, MNRAS 235, 269 — Doppler tomography by "
+        "back-projection (§2).",
+        "Horne 1985, MNRAS 213, 129 — MEM tomographic reconstruction "
+        "(not implemented; cited for completeness).",
+        "Marsh 2001, Lecture Notes in Physics 573 — astrotomography review.",
+    ]
+    long_description = (
+        "Back-projection of N phase-resolved spectra onto the (V_x, V_y) "
+        "plane. Pixels are averaged over the phases that contribute (NaN-"
+        "aware mean) so the phase-coverage footprint does not bleed into "
+        "the brightness map. JD_mid is read from each spectrum's "
+        "meta['jd_mid'], falling back to meta['dateobs'] + "
+        "meta['exptime_s'] via astropy.time.Time."
+    )
+    default_params: dict[str, Any] = {
+        "period_days": None,
+        "epoch_hjd": None,
+        "gamma_kms": 0.0,
+        "line_center_aa": 6562.82,
+        "velocity_window_kms": 1000.0,
+        "n_velocity": 121,
+    }
+    required_params = ["period_days", "epoch_hjd"]
+    param_descriptions = {
+        "period_days": "Orbital period of the binary (days).",
+        "epoch_hjd": "Reference epoch HJD of phase 0 (days).",
+        "gamma_kms": "Systemic velocity (km/s) added to the back-projection.",
+        "line_center_aa": "Rest wavelength (Å) of the line to tomogram.",
+        "velocity_window_kms": "Half-extent (km/s) of the V_x/V_y axes.",
+        "n_velocity": "Number of velocity samples per axis (odd, 11–401).",
+    }
+    input_requirements: list[str] = []  # validated dynamically
+    output_produces = ["extras.tomography_result", "metrics.n_spectra"]
+
+    def run(self, ctx: WorkContext, params: dict[str, Any]) -> AlgorithmOutput:
+        spectra = list(ctx.spectra or [])
+        if len(spectra) < 3:
+            return AlgorithmOutput.fail(
+                f"Need ≥ 3 spectra in ctx.spectra; got {len(spectra)}."
+            )
+
+        period = float(params["period_days"])
+        if period <= 0.0:
+            raise InvalidParameterError("period_days must be > 0.")
+        epoch_hjd = float(params["epoch_hjd"])
+        gamma_kms = float(params["gamma_kms"])
+        line_centre = float(params["line_center_aa"])
+        v_window = float(params["velocity_window_kms"])
+        if v_window <= 0.0:
+            raise InvalidParameterError("velocity_window_kms must be > 0.")
+        n_velocity = int(params["n_velocity"])
+        if not 11 <= n_velocity <= 401:
+            raise InvalidParameterError("n_velocity must be in [11, 401].")
+
+        velocity_grid = np.linspace(-v_window, +v_window, n_velocity)
+
+        rows: list[tuple[float, np.ndarray]] = []
+        skipped_no_jd = 0
+        skipped_bad_spec = 0
+        for spec in spectra:
+            jd_mid = _resolve_jd_mid(spec)
+            if jd_mid is None:
+                skipped_no_jd += 1
+                continue
+            excess = _line_excess_on_velocity_grid(spec, line_centre, velocity_grid)
+            if excess is None:
+                skipped_bad_spec += 1
+                continue
+            phase = ((jd_mid - epoch_hjd) / period) % 1.0
+            rows.append((float(phase), excess))
+
+        if len(rows) < 3:
+            return AlgorithmOutput.fail(
+                f"Only {len(rows)} usable spectra (need ≥ 3) — skipped "
+                f"{skipped_no_jd} for missing JD_mid and "
+                f"{skipped_bad_spec} for failed continuum / interpolation."
+            )
+
+        rows.sort(key=lambda row: row[0])
+        phases = np.asarray([row[0] for row in rows], dtype=np.float64)
+        trailed = np.stack([row[1] for row in rows], axis=0)
+        # NaN-aware: replace residual NaNs from np.interp by 0 before
+        # accumulation (they don't contribute, and "no data" ≠ "0 signal").
+        trailed_clean = np.where(np.isfinite(trailed), trailed, 0.0)
+        doppler_map = _back_project(
+            trailed_clean, phases, velocity_grid, gamma_kms, n_velocity,
+        )
+
+        result = {
+            "velocity_grid_kms": velocity_grid,
+            "phase_grid": phases,
+            "trailed_spectrogram": trailed,
+            "doppler_map": doppler_map,
+            "vx_axis_kms": velocity_grid,
+            "vy_axis_kms": velocity_grid,
+            "n_spectra": len(rows),
+            "n_skipped_no_jd": skipped_no_jd,
+            "n_skipped_bad_spec": skipped_bad_spec,
+            "period_days": period,
+            "epoch_hjd": epoch_hjd,
+            "gamma_kms": gamma_kms,
+            "line_center_aa": line_centre,
+        }
+        ctx.extras["tomography_result"] = result
+        ctx.metrics["n_spectra"] = float(len(rows))
+        ctx.metrics["period_days"] = period
+        ctx.metrics["epoch_hjd"] = epoch_hjd
+        ctx.metrics["gamma_kms"] = gamma_kms
+        ctx.metrics["line_center_aa"] = line_centre
+        return AlgorithmOutput.ok(
+            metrics={
+                "n_spectra": float(len(rows)),
+                "n_skipped_no_jd": float(skipped_no_jd),
+                "n_skipped_bad_spec": float(skipped_bad_spec),
+                "period_days": period,
+                "epoch_hjd": epoch_hjd,
+                "gamma_kms": gamma_kms,
+                "line_center_aa": line_centre,
+            },
+            artifacts={"tomography_result": result},
+            message=(
+                f"Doppler tomogram: {len(rows)} phase(s), "
+                f"V ∈ ±{v_window:.0f} km/s on {n_velocity}×{n_velocity} grid; "
+                f"peak |M| = {float(np.max(np.abs(doppler_map))):.3g}."
+            ),
+        )
+
+
+__all__ = ["DopplerTomogram"]