spectro-kernel 0.1.0__py3-none-any.whl

spectro_kernel/__init__.py

@@ -0,0 +1,89 @@
+"""spectro-kernel — a shared catalogue of astronomical spectroscopy algorithms.
+
+The public surface lives here so callers can do ``from spectro_kernel import ...`` for
+everything they need: the canonical types, the registry, the pipeline machinery and the
+pure I/O helpers. Algorithms register themselves lazily on first discovery.
+"""
+
+from __future__ import annotations
+
+from .base import AlgorithmOutput, BaseAlgorithm
+from .errors import (
+    AlgorithmNotFoundError,
+    InvalidParameterError,
+    PipelineError,
+    PresetNotFoundError,
+    SpectroKernelError,
+)
+from .io import read_ascii_spectrum, read_fits, write_ascii_spectrum, write_fits
+from .pipeline import Pipeline, PipelineBuilder, PipelineResult, PipelineStep
+from .presets import list_presets, load_preset
+from .registry import (
+    create_algorithm,
+    describe_algorithm,
+    get_algorithm,
+    has_algorithm,
+    list_algorithms,
+    list_categories,
+    register_algorithm,
+    run_algorithm,
+)
+from .types import (
+    AlgorithmCategory,
+    CatalogResult,
+    ImageFrame,
+    LightCurve,
+    LineFitResult,
+    Periodogram,
+    ProcessingStep,
+    SpectralLine,
+    Spectrum1D,
+    WorkContext,
+)
+from .version import __version__
+
+__all__ = [
+    "__version__",
+    # types
+    "AlgorithmCategory",
+    "CatalogResult",
+    "ImageFrame",
+    "LightCurve",
+    "LineFitResult",
+    "Periodogram",
+    "ProcessingStep",
+    "SpectralLine",
+    "Spectrum1D",
+    "WorkContext",
+    # algorithm contract
+    "BaseAlgorithm",
+    "AlgorithmOutput",
+    # registry
+    "register_algorithm",
+    "list_algorithms",
+    "list_categories",
+    "get_algorithm",
+    "create_algorithm",
+    "describe_algorithm",
+    "has_algorithm",
+    "run_algorithm",
+    # pipeline
+    "Pipeline",
+    "PipelineBuilder",
+    "PipelineResult",
+    "PipelineStep",
+    # presets
+    "load_preset",
+    "list_presets",
+    # io
+    "read_fits",
+    "write_fits",
+    "read_ascii_spectrum",
+    "write_ascii_spectrum",
+    # errors
+    "SpectroKernelError",
+    "AlgorithmNotFoundError",
+    "InvalidParameterError",
+    "PipelineError",
+    "PresetNotFoundError",
+]

spectro_kernel/adapters/__init__.py

@@ -0,0 +1,8 @@
+"""External-library adapters.
+
+Each module in this package wraps a domain library (astropy, specutils, astroquery,
+easyspec, …) behind the same algorithm interface as the native spectro-kernel
+algorithms. That is what makes the *we don't reinvent* principle visible: the same
+operation can be served either by our own implementation or by the canonical pro
+library, side by side in the catalogue.
+"""

spectro_kernel/adapters/easyspec.py

@@ -0,0 +1,47 @@
+"""Adapter scaffold for `easyspec` (Lobão et al.) — the CCD-reduction shelf option.
+
+`easyspec` (https://pypi.org/project/easyspec/) is a reduction toolkit oriented at
+notebook use: it offers stateful classes whose methods take you from raw FITS frames
+to a calibrated 1D spectrum, with rich plotting along the way. The native
+``spectro_kernel.algorithms.reduction`` algorithms cover the same operations as
+small, stateless, pipeline-friendly building blocks.
+
+Both have a place. This module is the bridge: as adapters land here, the catalogue
+will expose *both* paths so the user picks per operation:
+
+| Operation | Native (`reduction/`) | Easyspec (`adapters/easyspec`) |
+|-----------|-----------------------|--------------------------------|
+| master bias / dark / flat | `bias_combine` | `cleaning.master(kind="bias"…)` |
+| flat-fielding | `flat_normalize` | `cleaning.flatten` |
+| cosmic rays | `clip_cosmic_rays` (L.A.Cosmic) | `cleaning.CR_and_gain_corrections` |
+| 1D extraction | `extract_spectrum_sum` | `extraction.tracing` + `extracting` |
+| wavelength calibration | `wavelength_calibrate_polynomial` | `extraction.wavelength_calibration` |
+| flux calibration | (planned) | `extraction.target_flux_calibration` |
+
+Status: scaffold. The native path is complete and tested; easyspec wrappers will land
+incrementally so they fit our stateless contract (no plotting during execution, no
+required file paths). Install support is available now via the `reduction` extra:
+
+    pip install "spectro-kernel[reduction]"
+
+When the wrappers are in, they will register conditionally — the catalogue degrades
+gracefully if easyspec is not installed.
+"""
+
+from __future__ import annotations
+
+try:  # presence flag for downstream wrappers
+    import easyspec as _easyspec  # noqa: F401
+
+    EASYSPEC_AVAILABLE = True
+    EASYSPEC_VERSION = getattr(_easyspec, "__version__", "unknown")
+except ImportError:  # pragma: no cover - depends on install extras
+    EASYSPEC_AVAILABLE = False
+    EASYSPEC_VERSION = None
+
+
+# No algorithms registered yet — the wrappers will be added under
+# spectro_kernel/algorithms/reduction/, each marked `backend = "easyspec"` and
+# importing the helpers from this module.
+
+__all__ = ["EASYSPEC_AVAILABLE", "EASYSPEC_VERSION"]

spectro_kernel/algorithms/__init__.py

@@ -0,0 +1,20 @@
+"""The algorithm catalogue, with automatic discovery.
+
+Importing this package walks every submodule so that each ``@register_algorithm``
+decorator runs and the registry is fully populated. Adding an algorithm is therefore
+just adding a file under ``algorithms/<category>/`` — nothing else to wire up.
+"""
+
+from __future__ import annotations
+
+import importlib
+import pkgutil
+
+
+def _discover() -> None:
+    """Import every submodule so its algorithms register themselves."""
+    for module_info in pkgutil.walk_packages(__path__, prefix=__name__ + "."):
+        importlib.import_module(module_info.name)
+
+
+_discover()

spectro_kernel/algorithms/_common.py

@@ -0,0 +1,56 @@
+"""Numerical helpers shared by several algorithms.
+
+This module registers no algorithm; it only factors out maths used in more than one
+place so there is one implementation, not five.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def fit_polynomial_continuum(
+    wavelength: np.ndarray,
+    flux: np.ndarray,
+    *,
+    order: int = 3,
+    sigma_clip: float = 3.0,
+    iterations: int = 3,
+) -> np.ndarray:
+    """Fit a sigma-clipped polynomial continuum and return it sampled on *wavelength*.
+
+    The fit runs on a rescaled abscissa (``numpy.polynomial.Polynomial.fit`` handles the
+    domain mapping) so it stays well-conditioned even for raw Ångström values. Samples
+    deviating by more than *sigma_clip* standard deviations are dropped between
+    iterations, which keeps emission/absorption lines out of the continuum estimate.
+    """
+    x = np.asarray(wavelength, dtype=np.float64)
+    y = np.asarray(flux, dtype=np.float64)
+    mask = np.isfinite(y)
+    if mask.sum() <= order + 1:
+        return np.full_like(y, float(np.nanmedian(y)))
+
+    for _ in range(max(1, iterations)):
+        model_poly = np.polynomial.Polynomial.fit(x[mask], y[mask], deg=order)
+        residual = y - model_poly(x)
+        std = float(np.std(residual[mask]))
+        if std == 0.0:
+            break
+        new_mask = mask & (np.abs(residual) < sigma_clip * std)
+        if new_mask.sum() <= order + 1 or new_mask.sum() == mask.sum():
+            mask = new_mask if new_mask.sum() > order + 1 else mask
+            break
+        mask = new_mask
+
+    return np.polynomial.Polynomial.fit(x[mask], y[mask], deg=order)(x)
+
+
+def r_squared(observed: np.ndarray, modelled: np.ndarray) -> float:
+    """Return the coefficient of determination of *modelled* against *observed*."""
+    observed = np.asarray(observed, dtype=np.float64)
+    modelled = np.asarray(modelled, dtype=np.float64)
+    ss_res = float(np.sum((observed - modelled) ** 2))
+    ss_tot = float(np.sum((observed - np.mean(observed)) ** 2))
+    if ss_tot == 0.0:
+        return 0.0
+    return 1.0 - ss_res / ss_tot

spectro_kernel/algorithms/advanced/__init__.py

@@ -0,0 +1 @@
+"""Advanced spectroscopy algorithms — niche but useful when you need them."""

spectro_kernel/algorithms/advanced/aperture_photometry.py

@@ -0,0 +1,132 @@
+"""Algorithm: differential aperture photometry on a 2D image (photutils)."""
+
+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, WorkContext
+
+try:
+    from photutils.aperture import (
+        ApertureStats,
+        CircularAnnulus,
+        CircularAperture,
+        aperture_photometry,
+    )
+
+    _HAVE_PHOTUTILS = True
+except ImportError:  # pragma: no cover - depends on install extras
+    _HAVE_PHOTUTILS = False
+
+
+if _HAVE_PHOTUTILS:
+
+    @register_algorithm(
+        "aperture_photometry",
+        category=AlgorithmCategory.ADVANCED,
+        version="1.0.0",
+    )
+    class AperturePhotometry(BaseAlgorithm):
+        """Differential aperture photometry on ``ctx.image`` (photutils).
+
+        Measure the brightness of a target relative to one or more comparison stars
+        — the standard amateur/AAVSO recipe. Each aperture's background is taken from
+        a concentric sky annulus and subtracted before integration.
+        """
+
+        backend = "photutils"
+        references = [
+            "Bradley et al. — Astropy Photutils (https://photutils.readthedocs.io/).",
+            "AAVSO Guide to CCD Photometry.",
+        ]
+        long_description = (
+            "Provide the target's (x, y) pixel coordinates and one or more comparison "
+            "stars. The differential magnitude for each comparison is "
+            "-2.5 * log10(target_flux / comp_flux); positive means the target is "
+            "fainter than the comparison."
+        )
+        default_params = {
+            "target_xy": None,
+            "comparison_xy": None,
+            "aperture_radius": 5.0,
+            "annulus_in_radius": 8.0,
+            "annulus_out_radius": 12.0,
+        }
+        required_params = ["target_xy", "comparison_xy"]
+        param_descriptions = {
+            "target_xy": "Target (x, y) pixel coordinates (length-2 list).",
+            "comparison_xy": "List of (x, y) coordinates for comparison stars.",
+            "aperture_radius": "Aperture radius (pixels) for source extraction.",
+            "annulus_in_radius": "Inner radius of the sky annulus (pixels).",
+            "annulus_out_radius": "Outer radius of the sky annulus (pixels).",
+        }
+        input_requirements = ["image"]
+        output_produces = ["extras.photometry", "metrics.target_flux"]
+
+        def run(self, ctx: WorkContext, params: dict[str, Any]) -> AlgorithmOutput:
+            target = list(params["target_xy"])
+            comparisons = [list(c) for c in params["comparison_xy"]]
+            if len(target) != 2:
+                raise InvalidParameterError("target_xy must be a (x, y) pair.")
+            if not comparisons:
+                raise InvalidParameterError("Need at least one comparison star.")
+            r_ap = float(params["aperture_radius"])
+            r_in = float(params["annulus_in_radius"])
+            r_out = float(params["annulus_out_radius"])
+            if not (r_ap > 0 and r_in > r_ap and r_out > r_in):
+                raise InvalidParameterError(
+                    "Need 0 < aperture_radius < annulus_in_radius < annulus_out_radius."
+                )
+
+            positions = [tuple(target)] + [tuple(c) for c in comparisons]
+            aperture = CircularAperture(positions, r=r_ap)
+            annulus = CircularAnnulus(positions, r_in=r_in, r_out=r_out)
+            image = ctx.image.data
+
+            # Background per-source (median of the annulus, photutils helper).
+            bkg_stats = ApertureStats(image, annulus)
+            bkg_median = np.asarray(bkg_stats.median, dtype=np.float64)
+
+            phot = aperture_photometry(image, aperture)
+            ap_area = aperture.area
+            raw = np.asarray(phot["aperture_sum"], dtype=np.float64)
+            net = raw - bkg_median * ap_area
+
+            target_flux = float(net[0])
+            comp_fluxes = net[1:].astype(float).tolist()
+
+            mags = []
+            for cf in comp_fluxes:
+                if cf > 0.0 and target_flux > 0.0:
+                    mags.append(-2.5 * math.log10(target_flux / cf))
+                else:
+                    mags.append(None)
+
+            ctx.metrics["target_flux"] = target_flux
+            ctx.extras["photometry"] = {
+                "target_xy": target,
+                "target_flux": target_flux,
+                "comparison_xy": comparisons,
+                "comparison_flux": comp_fluxes,
+                "differential_magnitudes": mags,
+                "aperture_radius": r_ap,
+                "annulus_radii": [r_in, r_out],
+                "background_per_source": bkg_median.tolist(),
+            }
+            return AlgorithmOutput.ok(
+                metrics={
+                    "target_flux": target_flux,
+                    "n_comparisons": float(len(comp_fluxes)),
+                },
+                artifacts={"photometry": ctx.extras["photometry"]},
+                message=(
+                    f"Differential photometry: target flux = {target_flux:.3g} "
+                    f"vs {len(comp_fluxes)} comparison(s)."
+                ),
+            )

spectro_kernel/algorithms/advanced/disentangle_sb2.py

@@ -0,0 +1,165 @@
+"""Algorithm: iterative wavelength-domain disentangling of an SB2 binary."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import astropy.constants as const
+import astropy.units as u
+import numpy as np
+
+from ...base import AlgorithmOutput, BaseAlgorithm
+from ...errors import InvalidParameterError
+from ...registry import register_algorithm
+from ...types import AlgorithmCategory, Spectrum1D, WorkContext
+
+_C_KMS = const.c.to(u.km / u.s).value
+
+
+@register_algorithm(
+    "disentangle_sb2",
+    category=AlgorithmCategory.ADVANCED,
+    version="1.0.0",
+)
+class DisentangleSb2(BaseAlgorithm):
+    """Separate the spectra of the two components of an SB2 spectroscopic binary.
+
+    Given several spectra of the same binary at orbital phases where the radial
+    velocities of the primary and secondary differ enough to break their degeneracy,
+    plus the per-spectrum velocities for both components, this algorithm reconstructs
+    each component's rest-frame spectrum.
+    """
+
+    backend = "numpy"
+    references = [
+        "Hadrava 1995, A&AS 114, 393 — Fourier-domain disentangling (original).",
+        "Simon & Sturm 1994, A&A 281, 286 — wavelength-domain spectral separation.",
+    ]
+    long_description = (
+        "Implements a simplified iterative wavelength-domain separation. All "
+        "observations are resampled onto a common log-wavelength grid so that a "
+        "Doppler shift is a constant number of samples. At each iteration the "
+        "current estimate of one component is removed from every observation in the "
+        "other component's rest frame, and the new estimate is the average of the "
+        "residuals. Stores ``primary_spectrum`` and ``secondary_spectrum`` in "
+        "``ctx.extras``."
+    )
+    default_params = {
+        "v1_kms": None,
+        "v2_kms": None,
+        "n_iter": 30,
+        "n_grid": 4096,
+    }
+    required_params = ["v1_kms", "v2_kms"]
+    param_descriptions = {
+        "v1_kms": "List of per-spectrum primary velocities (km/s, length = len(ctx.spectra)).",
+        "v2_kms": "List of per-spectrum secondary velocities (km/s, same length).",
+        "n_iter": "Number of iterations of the alternating subtraction.",
+        "n_grid": "Number of log-wavelength samples on the common grid.",
+    }
+    input_requirements = ["spectra"]
+    output_produces = ["extras.primary_spectrum", "extras.secondary_spectrum"]
+
+    def run(self, ctx: WorkContext, params: dict[str, Any]) -> AlgorithmOutput:
+        spectra = ctx.spectra
+        v1 = np.asarray(params["v1_kms"], dtype=np.float64)
+        v2 = np.asarray(params["v2_kms"], dtype=np.float64)
+        if v1.size != len(spectra) or v2.size != len(spectra):
+            raise InvalidParameterError(
+                "v1_kms and v2_kms must have the same length as ctx.spectra."
+            )
+        if len(spectra) < 2:
+            return AlgorithmOutput.fail(
+                "Need at least 2 spectra at different phases to disentangle SB2."
+            )
+
+        wmin = max(s.wavelength_min for s in spectra)
+        wmax = min(s.wavelength_max for s in spectra)
+        if wmin >= wmax:
+            return AlgorithmOutput.fail("Spectra do not overlap in wavelength.")
+
+        n = int(params["n_grid"])
+        log_grid = np.linspace(np.log(wmin), np.log(wmax), n)
+        wave_grid = np.exp(log_grid)
+        delta_log = (log_grid[-1] - log_grid[0]) / (n - 1)
+        v_per_pixel = _C_KMS * delta_log
+
+        # Resample observations to the common log-wavelength grid (in the observed frame).
+        obs = np.stack(
+            [np.interp(wave_grid, s.wavelength, s.flux) for s in spectra]
+        ).astype(np.float64)
+
+        n_iter = int(params["n_iter"])
+        return _disentangle(
+            ctx, obs, v1, v2, wave_grid, v_per_pixel, n_iter
+        )
+
+
+def _shift(values: np.ndarray, shift_pixels: float) -> np.ndarray:
+    """Shift *values* along its index by ``shift_pixels`` (positive = redward)."""
+    idx = np.arange(values.size, dtype=np.float64)
+    return np.interp(idx - shift_pixels, idx, values, left=np.nan, right=np.nan)
+
+
+def _disentangle(
+    ctx: WorkContext,
+    obs: np.ndarray,
+    v1: np.ndarray,
+    v2: np.ndarray,
+    wave_grid: np.ndarray,
+    v_per_pixel: float,
+    n_iter: int,
+) -> AlgorithmOutput:
+    """Run the alternating wavelength-domain separation."""
+    n_obs = obs.shape[0]
+    shifts1 = v1 / v_per_pixel
+    shifts2 = v2 / v_per_pixel
+
+    primary = np.nanmean(obs, axis=0).copy()        # rough first guess
+    secondary = np.zeros_like(primary)
+
+    for _ in range(n_iter):
+        # Pull every obs back into primary rest frame, subtract the secondary's
+        # contribution in that same frame, average. Re-do symmetrically for the
+        # secondary.
+        prim_estimates = np.array(
+            [
+                _shift(obs[i], -shifts1[i]) - _shift(secondary, shifts2[i] - shifts1[i])
+                for i in range(n_obs)
+            ]
+        )
+        primary = np.nanmean(prim_estimates, axis=0)
+
+        sec_estimates = np.array(
+            [
+                _shift(obs[i], -shifts2[i]) - _shift(primary, shifts1[i] - shifts2[i])
+                for i in range(n_obs)
+            ]
+        )
+        secondary = np.nanmean(sec_estimates, axis=0)
+
+    # Replace any residual NaN (at frame edges where the shift extrapolates) with 0.
+    primary = np.nan_to_num(primary, nan=0.0)
+    secondary = np.nan_to_num(secondary, nan=0.0)
+
+    ref = ctx.spectra[0]
+    ctx.extras["primary_spectrum"] = Spectrum1D(
+        wavelength=wave_grid.copy(),
+        flux=primary,
+        flux_unit=ref.flux_unit,
+        wavelength_unit=ref.wavelength_unit,
+        meta={"sb2": "primary", "n_iter": int(n_iter)},
+    )
+    ctx.extras["secondary_spectrum"] = Spectrum1D(
+        wavelength=wave_grid.copy(),
+        flux=secondary,
+        flux_unit=ref.flux_unit,
+        wavelength_unit=ref.wavelength_unit,
+        meta={"sb2": "secondary", "n_iter": int(n_iter)},
+    )
+    return AlgorithmOutput.ok(
+        metrics={"n_iter": float(n_iter), "n_grid": float(wave_grid.size)},
+        message=(
+            f"Disentangled SB2 from {n_obs} epochs over {wave_grid.size} log-λ samples."
+        ),
+    )

spectro_kernel/algorithms/catalogs/__init__.py

@@ -0,0 +1 @@
+"""Catalogue algorithms — queries to external astronomical databases."""

spectro_kernel/algorithms/catalogs/gaia.py

@@ -0,0 +1,106 @@
+"""Algorithm: query the Gaia archive (TAP) for astrometry/photometry 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.gaia import Gaia as _Gaia
+
+    _HAVE_ASTROQUERY = True
+except ImportError:  # pragma: no cover - depends on install extras
+    _HAVE_ASTROQUERY = False
+
+
+if _HAVE_ASTROQUERY:
+
+    @register_algorithm("gaia_query", category=AlgorithmCategory.CATALOG, version="1.0.0")
+    class GaiaQuery(BaseAlgorithm):
+        """Cone-search the Gaia archive around ICRS coordinates.
+
+        Returns the nearest record as a :class:`CatalogResult` stored under the source
+        identifier in ``ctx.catalog_lookups``.
+        """
+
+        backend = "astroquery"
+        references = [
+            "Gaia Collaboration 2016, A&A 595, A1 — the Gaia mission",
+            "Salgado et al. 2017 — Gaia archive TAP+ access",
+            "Ginsburg et al. 2019, AJ 157, 98 — astroquery",
+        ]
+        long_description = (
+            "Requires network access and the optional 'catalogs' extra. By default "
+            "queries the latest release available via astroquery.gaia. Use `data_release` "
+            "to pin a specific release such as 'DR3' or 'DR2'."
+        )
+        default_params = {
+            "ra_deg": None,
+            "dec_deg": None,
+            "radius_arcsec": 5.0,
+            "data_release": None,
+        }
+        required_params = ["ra_deg", "dec_deg"]
+        param_descriptions = {
+            "ra_deg": "Right ascension (ICRS) in degrees.",
+            "dec_deg": "Declination (ICRS) in degrees.",
+            "radius_arcsec": "Cone-search radius around the position.",
+            "data_release": "Gaia release table to query (e.g. 'gaiadr3.gaia_source').",
+        }
+        input_requirements: list[str] = []
+        output_produces = ["catalog_lookups"]
+
+        def run(self, ctx: WorkContext, params: dict[str, Any]) -> AlgorithmOutput:
+            ra = float(params["ra_deg"])
+            dec = float(params["dec_deg"])
+            radius_deg = float(params["radius_arcsec"]) / 3600.0
+            table_name = params.get("data_release") or "gaiadr3.gaia_source"
+            adql = (
+                f"SELECT TOP 1 source_id, ra, dec, parallax, phot_g_mean_mag, "
+                f"DISTANCE(POINT('ICRS', ra, dec), POINT('ICRS', {ra}, {dec})) AS sep "
+                f"FROM {table_name} "
+                f"WHERE 1 = CONTAINS(POINT('ICRS', ra, dec), "
+                f"CIRCLE('ICRS', {ra}, {dec}, {radius_deg})) "
+                f"ORDER BY sep ASC"
+            )
+            try:
+                job = _Gaia.launch_job(adql)
+                table = job.get_results()
+            except Exception as exc:  # noqa: BLE001 - network/parse errors
+                return AlgorithmOutput.fail(f"Gaia query failed: {exc}")
+
+            if table is None or len(table) == 0:
+                result = CatalogResult(source="Gaia", query=f"{ra},{dec}")
+                key = f"gaia:{ra:.5f},{dec:.5f}"
+                ctx.catalog_lookups[key] = result
+                return AlgorithmOutput.ok(
+                    artifacts={"result": result.to_dict()},
+                    message=f"Gaia returned no source within {params['radius_arcsec']}\".",
+                )
+
+            row = table[0]
+            source_id = str(row["source_id"])
+            result = CatalogResult(
+                source=f"Gaia ({table_name})",
+                query=f"{ra},{dec}",
+                identifier=source_id,
+                ra_deg=float(row["ra"]),
+                dec_deg=float(row["dec"]),
+                fields={
+                    "parallax_mas": float(row["parallax"]) if row["parallax"] is not None else None,
+                    "G_mag": (
+                        float(row["phot_g_mean_mag"])
+                        if row["phot_g_mean_mag"] is not None
+                        else None
+                    ),
+                    "separation_deg": float(row["sep"]),
+                },
+            )
+            ctx.catalog_lookups[source_id] = result
+            return AlgorithmOutput.ok(
+                artifacts={"result": result.to_dict()},
+                message=f"Gaia source {source_id} at {row['sep']*3600:.2f}\".",
+            )