spectro-kernel 0.1.0__py3-none-any.whl

spectro_kernel/algorithms/catalogs/simbad.py

@@ -0,0 +1,113 @@
+"""Algorithm: resolve an object against the SIMBAD database.
+
+Requires the optional ``catalogs`` extra (``pip install spectro-kernel[catalogs]``).
+If astroquery is not installed the algorithm simply does not register, and the rest of
+the catalogue loads normally.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ...base import AlgorithmOutput, BaseAlgorithm
+from ...registry import register_algorithm
+from ...types import AlgorithmCategory, CatalogResult, WorkContext
+
+try:  # optional dependency
+    from astroquery.simbad import Simbad as _Simbad
+
+    _HAVE_ASTROQUERY = True
+except ImportError:  # pragma: no cover - depends on the install extras
+    _HAVE_ASTROQUERY = False
+
+
+def _cell(row: Any, *names: str) -> Any:
+    """Return the first present column value from *row*, matched case-insensitively."""
+    available = {str(c).lower(): c for c in row.colnames}
+    for name in names:
+        col = available.get(name.lower())
+        if col is not None:
+            value = row[col]
+            return None if value is None or str(value).strip() in ("", "--") else value
+    return None
+
+
+if _HAVE_ASTROQUERY:
+
+    @register_algorithm("simbad_query", category=AlgorithmCategory.CATALOG, version="1.0.0")
+    class SimbadQuery(BaseAlgorithm):
+        """Resolve an object name against SIMBAD and store the record in the context.
+
+        The normalised :class:`CatalogResult` (identifier, ICRS coordinates, object
+        type) is stored in ``ctx.catalog_lookups`` keyed by the queried name.
+        """
+
+        backend = "astroquery"
+        references = [
+            "Wenger et al. 2000, A&AS 143, 9 — the SIMBAD astronomical database",
+            "Ginsburg et al. 2019, AJ 157, 98 — astroquery",
+        ]
+        long_description = (
+            "Requires network access and the optional 'catalogs' extra. Results are not "
+            "cached by the algorithm itself; wrap it in a caching layer for batch use."
+        )
+        default_params = {"object_name": None}
+        required_params = ["object_name"]
+        param_descriptions = {"object_name": "Object identifier to resolve (e.g. 'Vega')."}
+        input_requirements: list[str] = []
+        output_produces = ["catalog_lookups"]
+
+        def run(self, ctx: WorkContext, params: dict[str, Any]) -> AlgorithmOutput:
+            name = str(params["object_name"])
+            try:
+                table = _Simbad.query_object(name)
+            except Exception as exc:  # noqa: BLE001 - network/parse errors
+                return AlgorithmOutput.fail(f"SIMBAD query failed: {exc}")
+
+            if table is None or len(table) == 0:
+                result = CatalogResult(source="SIMBAD", query=name)
+                ctx.catalog_lookups[name] = result
+                return AlgorithmOutput.ok(
+                    artifacts={"result": result.to_dict()},
+                    message=f"SIMBAD returned no match for {name!r}.",
+                )
+
+            row = table[0]
+            ra = _cell(row, "ra", "ra_d")
+            dec = _cell(row, "dec", "dec_d")
+            result = CatalogResult(
+                source="SIMBAD",
+                query=name,
+                identifier=_str_or_none(_cell(row, "main_id")),
+                ra_deg=_coord_to_deg(ra, is_ra=True),
+                dec_deg=_coord_to_deg(dec, is_ra=False),
+                object_type=_str_or_none(_cell(row, "otype")),
+                fields={"raw": {c: str(row[c]) for c in row.colnames}},
+            )
+            ctx.catalog_lookups[name] = result
+            return AlgorithmOutput.ok(
+                artifacts={"result": result.to_dict()},
+                message=f"SIMBAD resolved {name!r} to {result.identifier}.",
+            )
+
+
+def _str_or_none(value: Any) -> str | None:
+    return None if value is None else str(value).strip()
+
+
+def _coord_to_deg(value: Any, *, is_ra: bool) -> float | None:
+    """Convert a SIMBAD coordinate (degrees or sexagesimal) to decimal degrees."""
+    if value is None:
+        return None
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        pass
+    try:  # sexagesimal string
+        import astropy.units as u
+        from astropy.coordinates import Angle
+
+        unit = u.hourangle if is_ra else u.deg
+        return float(Angle(str(value), unit=unit).to(u.deg).value)
+    except Exception:  # noqa: BLE001
+        return None

spectro_kernel/algorithms/catalogs/vizier.py

@@ -0,0 +1,89 @@
+"""Algorithm: query VizieR for tabular catalogue data on an object."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ...base import AlgorithmOutput, BaseAlgorithm
+from ...registry import register_algorithm
+from ...types import AlgorithmCategory, CatalogResult, WorkContext
+
+try:
+    from astroquery.vizier import Vizier as _Vizier
+
+    _HAVE_ASTROQUERY = True
+except ImportError:  # pragma: no cover - depends on install extras
+    _HAVE_ASTROQUERY = False
+
+
+if _HAVE_ASTROQUERY:
+
+    @register_algorithm("vizier_query", category=AlgorithmCategory.CATALOG, version="1.0.0")
+    class VizierQuery(BaseAlgorithm):
+        """Look up an object in VizieR — the CDS table service.
+
+        Returns the first row of the first matching catalogue as a
+        :class:`CatalogResult` stored in ``ctx.catalog_lookups``.
+        """
+
+        backend = "astroquery"
+        references = [
+            "Ochsenbein, Bauer & Marcout 2000, A&AS 143, 23 — VizieR",
+            "Ginsburg et al. 2019, AJ 157, 98 — astroquery",
+        ]
+        long_description = (
+            "Requires network access and the optional 'catalogs' extra. By default the "
+            "row count per catalogue is capped at 5; set `row_limit` to change it."
+        )
+        default_params = {
+            "object_name": None,
+            "catalog": None,
+            "row_limit": 5,
+            "radius_arcsec": 5.0,
+        }
+        required_params = ["object_name"]
+        param_descriptions = {
+            "object_name": "Object identifier (e.g. 'HD 209458').",
+            "catalog": "Optional VizieR catalogue ID to restrict to (e.g. 'I/350/gaiaedr3').",
+            "row_limit": "Maximum number of rows to fetch per catalogue.",
+            "radius_arcsec": "Cone-search radius around the resolved position.",
+        }
+        input_requirements: list[str] = []
+        output_produces = ["catalog_lookups"]
+
+        def run(self, ctx: WorkContext, params: dict[str, Any]) -> AlgorithmOutput:
+            name = str(params["object_name"])
+            try:
+                v = _Vizier(row_limit=int(params["row_limit"]))
+                tables = (
+                    v.query_object(name, catalog=params["catalog"])
+                    if params["catalog"]
+                    else v.query_object(name)
+                )
+            except Exception as exc:  # noqa: BLE001 - network/parse errors
+                return AlgorithmOutput.fail(f"VizieR query failed: {exc}")
+
+            if tables is None or len(tables) == 0:
+                result = CatalogResult(source="VizieR", query=name)
+                ctx.catalog_lookups[name] = result
+                return AlgorithmOutput.ok(
+                    artifacts={"result": result.to_dict()},
+                    message=f"VizieR returned no match for {name!r}.",
+                )
+
+            first_table = tables[0]
+            row = first_table[0]
+            result = CatalogResult(
+                source=f"VizieR/{first_table.meta.get('name', '?')}",
+                query=name,
+                identifier=str(row.colnames[0]) if row.colnames else None,
+                fields={
+                    "n_tables": len(tables),
+                    "first_row": {c: str(row[c]) for c in row.colnames},
+                },
+            )
+            ctx.catalog_lookups[name] = result
+            return AlgorithmOutput.ok(
+                artifacts={"result": result.to_dict(), "n_tables": len(tables)},
+                message=f"VizieR returned {len(tables)} catalogue(s) for {name!r}.",
+            )

spectro_kernel/algorithms/continuum/__init__.py

@@ -0,0 +1 @@
+"""Continuum algorithms — normalisation and subtraction of the spectral continuum."""

spectro_kernel/algorithms/continuum/compare_normalisations.py

@@ -0,0 +1,116 @@
+"""Algorithm: run every continuum-normalisation variant side-by-side.
+
+A *guided shelf* helper: instead of asking the user to pick between
+``normalize_polynomial`` / ``normalize_percentile`` / ``normalize_max`` /
+``normalize_edges`` blind, this runs all of them on the same input and stores
+each result so the caller can compare and pick. Pair with a Plotly viz tool to
+render the overlay.
+"""
+
+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
+
+_DEFAULT_METHODS: tuple[str, ...] = (
+    "normalize_polynomial",
+    "normalize_percentile",
+    "normalize_max",
+    "normalize_edges",
+)
+
+
+@register_algorithm(
+    "compare_normalisations",
+    category=AlgorithmCategory.CONTINUUM,
+    version="1.0.0",
+)
+class CompareNormalisations(BaseAlgorithm):
+    """Run every continuum-normalisation method on ``ctx.spectrum`` and collect them.
+
+    Each method is invoked on a deep copy of the context so the original spectrum
+    stays untouched; the resulting normalised spectra are stored in
+    ``ctx.extras['normalisations']`` as a dict ``{method_name: Spectrum1D}``.
+    Pairwise RMS differences between any two methods are recorded in
+    ``ctx.metrics`` so the caller can quantify how close the choices are.
+    """
+
+    backend = "numpy"
+    references = [
+        "Catalogue normalise_* algorithms; this wrapper is composition only.",
+    ]
+    long_description = (
+        "The Spectrum1D ``ctx.spectrum`` you pass in is *not* modified — only "
+        "``ctx.extras['normalisations']`` is populated. To then apply one of the "
+        "results, copy it back into ``ctx.spectrum`` yourself."
+    )
+    default_params = {
+        "methods": list(_DEFAULT_METHODS),
+        "per_method_params": {},
+    }
+    param_descriptions = {
+        "methods": "Names of normalisation algorithms to run (defaults to the 4 native ones).",
+        "per_method_params": "Optional dict {method_name: {param: value}} for non-default params.",
+    }
+    input_requirements = ["spectrum"]
+    output_produces = ["extras.normalisations", "metrics.normalisations_rms"]
+
+    def run(self, ctx: WorkContext, params: dict[str, Any]) -> AlgorithmOutput:
+        from ...registry import run_algorithm  # noqa: PLC0415 - avoid import cycle
+
+        methods = list(params["methods"]) if params["methods"] else list(_DEFAULT_METHODS)
+        if not methods:
+            raise InvalidParameterError("methods must contain at least one algorithm name.")
+        per_method = params.get("per_method_params") or {}
+        original_spectrum = ctx.spectrum
+
+        results = {}
+        failures = []
+        for method in methods:
+            try:
+                trial = ctx.copy()
+                method_params = dict(per_method.get(method, {}))
+                output = run_algorithm(method, trial, method_params, raise_on_error=False)
+                if output.success and trial.spectrum is not None:
+                    results[method] = trial.spectrum
+                else:
+                    failures.append((method, output.error or "no spectrum produced"))
+            except Exception as exc:  # noqa: BLE001 - any failure is recorded
+                failures.append((method, f"{type(exc).__name__}: {exc}"))
+
+        # Restore the original spectrum on the working context.
+        ctx.spectrum = original_spectrum
+        ctx.extras["normalisations"] = results
+
+        # Pairwise RMS — only between methods sharing the input grid (true for the
+        # native normalize_* algos, which leave the wavelength axis untouched).
+        names = sorted(results)
+        pairwise_rms: dict[str, float] = {}
+        for i, a in enumerate(names):
+            for b in names[i + 1 :]:
+                fa, fb = results[a].flux, results[b].flux
+                if fa.shape == fb.shape:
+                    rms = float(np.sqrt(np.nanmean((fa - fb) ** 2)))
+                    pairwise_rms[f"{a}__vs__{b}"] = rms
+        for key, value in pairwise_rms.items():
+            ctx.metrics[f"normalisations_rms[{key}]"] = value
+
+        message = (
+            f"Compared {len(results)}/{len(methods)} normalisations."
+            + ("" if not failures else f" Failed: {[f[0] for f in failures]}.")
+        )
+        return AlgorithmOutput.ok(
+            metrics={"n_methods": float(len(results))},
+            artifacts={
+                "methods_run": names,
+                "pairwise_rms": pairwise_rms,
+                "failures": failures,
+            },
+            message=message,
+        )

spectro_kernel/algorithms/continuum/normalize_edges.py

@@ -0,0 +1,59 @@
+"""Algorithm: normalise a spectrum using a continuum fitted on its edges only."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+from ...base import AlgorithmOutput, BaseAlgorithm
+from ...errors import InvalidParameterError
+from ...registry import register_algorithm
+from ...types import AlgorithmCategory, WorkContext
+
+
+@register_algorithm("normalize_edges", category=AlgorithmCategory.CONTINUUM, version="1.0.0")
+class NormalizeEdges(BaseAlgorithm):
+    """Normalise a spectrum using a continuum fitted only on its line-free edges.
+
+    A low-order polynomial is fitted through the outer fraction of the spectrum at each
+    end — assumed to be pure continuum — then extrapolated across the whole range and
+    divided out. The right tool for a narrow window centred on a single line, where a
+    global fit would be biased by the line itself.
+    """
+
+    default_params = {"edge_fraction": 0.15, "order": 1}
+    param_descriptions = {
+        "edge_fraction": "Fraction of the spectrum, at each end, used to fit the continuum.",
+        "order": "Polynomial order of the edge continuum fit (1 = linear).",
+    }
+    input_requirements = ["spectrum"]
+    output_produces = ["spectrum", "metrics.continuum_median"]
+
+    def run(self, ctx: WorkContext, params: dict[str, Any]) -> AlgorithmOutput:
+        fraction = float(params["edge_fraction"])
+        order = int(params["order"])
+        if not 0.0 < fraction < 0.5:
+            raise InvalidParameterError("edge_fraction must be in the interval (0, 0.5).")
+
+        spec = ctx.spectrum
+        n_edge = max(order + 1, int(spec.npix * fraction))
+        if spec.npix < 2 * n_edge:
+            return AlgorithmOutput.fail("Spectrum too short for the requested edge windows.")
+
+        edge_idx = np.r_[0:n_edge, spec.npix - n_edge : spec.npix]
+        poly = np.polynomial.Polynomial.fit(
+            spec.wavelength[edge_idx], spec.flux[edge_idx], deg=order
+        )
+        continuum = poly(spec.wavelength)
+        safe = np.where(continuum == 0.0, np.nan, continuum)
+
+        out = spec.with_flux(spec.flux / safe, flux_unit="normalized")
+        if spec.uncertainty is not None:
+            out.uncertainty = spec.uncertainty / np.abs(safe)
+        out.meta["continuum_method"] = "edges"
+        ctx.spectrum = out
+        return AlgorithmOutput.ok(
+            metrics={"continuum_median": float(np.nanmedian(continuum))},
+            message="Continuum fitted on the edges and normalised to unity.",
+        )

spectro_kernel/algorithms/continuum/normalize_max.py

@@ -0,0 +1,42 @@
+"""Algorithm: normalise a spectrum by its maximum flux."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+from ...base import AlgorithmOutput, BaseAlgorithm
+from ...errors import InvalidParameterError
+from ...registry import register_algorithm
+from ...types import AlgorithmCategory, WorkContext
+
+
+@register_algorithm("normalize_max", category=AlgorithmCategory.CONTINUUM, version="1.0.0")
+class NormalizeMax(BaseAlgorithm):
+    """Normalise a spectrum by dividing the flux by its maximum value.
+
+    The simplest possible normalisation: the peak becomes 1.0. Appropriate for
+    emission-line spectra or for quick visual comparison; it is sensitive to outliers,
+    so smooth or clip cosmic rays first.
+    """
+
+    default_params: dict[str, Any] = {}
+    input_requirements = ["spectrum"]
+    output_produces = ["spectrum", "metrics.max_flux"]
+
+    def run(self, ctx: WorkContext, params: dict[str, Any]) -> AlgorithmOutput:
+        spec = ctx.spectrum
+        peak = float(np.nanmax(spec.flux))
+        if peak == 0.0:
+            raise InvalidParameterError("Maximum flux is zero; cannot normalise.")
+
+        out = spec.with_flux(spec.flux / peak, flux_unit="normalized")
+        if spec.uncertainty is not None:
+            out.uncertainty = spec.uncertainty / abs(peak)
+        out.meta["continuum_method"] = "max"
+        ctx.spectrum = out
+        return AlgorithmOutput.ok(
+            metrics={"max_flux": peak},
+            message=f"Normalised by the maximum flux ({peak:.4g}).",
+        )

spectro_kernel/algorithms/continuum/normalize_percentile.py

@@ -0,0 +1,54 @@
+"""Algorithm: normalise a spectrum by a high flux percentile."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+from ...base import AlgorithmOutput, BaseAlgorithm
+from ...errors import InvalidParameterError
+from ...registry import register_algorithm
+from ...types import AlgorithmCategory, WorkContext
+
+
+@register_algorithm(
+    "normalize_percentile", category=AlgorithmCategory.CONTINUUM, version="1.0.0"
+)
+class NormalizePercentile(BaseAlgorithm):
+    """Normalise a spectrum by dividing the flux by a high percentile of itself.
+
+    A fast, parameter-light continuum estimate: the chosen percentile (95 by default)
+    approximates the continuum level for spectra dominated by absorption lines. Cheaper
+    and more robust than a polynomial fit, but it assumes a roughly flat continuum.
+    """
+
+    default_params = {"percentile": 95.0}
+    param_descriptions = {
+        "percentile": "Flux percentile (0-100) taken as the continuum level."
+    }
+    input_requirements = ["spectrum"]
+    output_produces = ["spectrum", "metrics.continuum_level"]
+
+    def run(self, ctx: WorkContext, params: dict[str, Any]) -> AlgorithmOutput:
+        percentile = float(params["percentile"])
+        if not 0.0 < percentile <= 100.0:
+            raise InvalidParameterError("percentile must be in the interval (0, 100].")
+
+        spec = ctx.spectrum
+        level = float(np.nanpercentile(spec.flux, percentile))
+        if level == 0.0:
+            raise InvalidParameterError(
+                f"The {percentile}th percentile of the flux is zero; cannot normalise."
+            )
+
+        out = spec.with_flux(spec.flux / level, flux_unit="normalized")
+        if spec.uncertainty is not None:
+            out.uncertainty = spec.uncertainty / abs(level)
+        out.meta["continuum_method"] = f"percentile_{percentile:g}"
+        ctx.spectrum = out
+
+        return AlgorithmOutput.ok(
+            metrics={"continuum_level": level},
+            message=f"Normalised by the {percentile:g}th flux percentile ({level:.4g}).",
+        )

spectro_kernel/algorithms/continuum/normalize_polynomial.py

@@ -0,0 +1,62 @@
+"""Algorithm: normalise a spectrum by a sigma-clipped polynomial continuum."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+from ...base import AlgorithmOutput, BaseAlgorithm
+from ...registry import register_algorithm
+from ...types import AlgorithmCategory, WorkContext
+from .._common import fit_polynomial_continuum
+
+
+@register_algorithm(
+    "normalize_polynomial", category=AlgorithmCategory.CONTINUUM, version="1.0.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.
+    """
+
+    long_description = (
+        "Robust against absorption/emission lines thanks to iterative sigma clipping. "
+        "Use a low order (2-4) for a slowly varying continuum; higher orders risk "
+        "absorbing real spectral features."
+    )
+    default_params = {"order": 3, "sigma_clip": 3.0, "iterations": 3}
+    param_descriptions = {
+        "order": "Polynomial degree of the continuum fit.",
+        "sigma_clip": "Reject samples beyond this many standard deviations per iteration.",
+        "iterations": "Number of sigma-clipping iterations.",
+    }
+    input_requirements = ["spectrum"]
+    output_produces = ["spectrum", "metrics.continuum_median"]
+
+    def run(self, ctx: WorkContext, params: dict[str, Any]) -> AlgorithmOutput:
+        spec = ctx.spectrum
+        continuum = fit_polynomial_continuum(
+            spec.wavelength,
+            spec.flux,
+            order=int(params["order"]),
+            sigma_clip=float(params["sigma_clip"]),
+            iterations=int(params["iterations"]),
+        )
+        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"
+        ctx.spectrum = out
+
+        metrics = {
+            "continuum_median": float(np.nanmedian(continuum)),
+            "normalized_rms": float(np.nanstd(normalised)),
+        }
+        return AlgorithmOutput.ok(metrics=metrics, message="Continuum normalised to unity.")

spectro_kernel/algorithms/continuum/subtract_continuum.py

@@ -0,0 +1,56 @@
+"""Algorithm: subtract a fitted polynomial continuum from a spectrum."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+from ...base import AlgorithmOutput, BaseAlgorithm
+from ...registry import register_algorithm
+from ...types import AlgorithmCategory, WorkContext
+from .._common import fit_polynomial_continuum
+
+
+@register_algorithm(
+    "subtract_continuum", category=AlgorithmCategory.CONTINUUM, version="1.0.0"
+)
+class SubtractContinuum(BaseAlgorithm):
+    """Subtract a sigma-clipped polynomial continuum, leaving the line residual.
+
+    Unlike ``normalize_polynomial`` (which divides), this subtracts the continuum so the
+    result is centred on zero — the natural input for emission-line detection and
+    equivalent-width work.
+    """
+
+    default_params = {"order": 3, "sigma_clip": 3.0, "iterations": 3}
+    param_descriptions = {
+        "order": "Polynomial degree of the continuum fit.",
+        "sigma_clip": "Reject samples beyond this many standard deviations per iteration.",
+        "iterations": "Number of sigma-clipping iterations.",
+    }
+    input_requirements = ["spectrum"]
+    output_produces = ["spectrum", "metrics.continuum_median"]
+
+    def run(self, ctx: WorkContext, params: dict[str, Any]) -> AlgorithmOutput:
+        spec = ctx.spectrum
+        continuum = fit_polynomial_continuum(
+            spec.wavelength,
+            spec.flux,
+            order=int(params["order"]),
+            sigma_clip=float(params["sigma_clip"]),
+            iterations=int(params["iterations"]),
+        )
+        residual = spec.flux - continuum
+
+        out = spec.with_flux(residual)
+        out.meta["continuum_method"] = "polynomial_subtracted"
+        ctx.spectrum = out
+
+        return AlgorithmOutput.ok(
+            metrics={
+                "continuum_median": float(np.nanmedian(continuum)),
+                "residual_rms": float(np.nanstd(residual)),
+            },
+            message="Polynomial continuum subtracted.",
+        )

spectro_kernel/algorithms/corrections/__init__.py

@@ -0,0 +1 @@
+"""Correction algorithms — move a spectrum between reference frames."""