spectro-kernel 0.8.0__tar.gz → 0.8.1__tar.gz

{spectro_kernel-0.8.0 → spectro_kernel-0.8.1}/CHANGELOG.md

@@ -6,6 +6,36 @@ Until `1.0.0` the public API may change between minor versions.
 
 ## [Unreleased]
 
+## [0.8.1] — 2026-09-26
+
+One native brick, the last of the September audit's "trivial and already requested"
+gaps (item 1 of its catalogue table), plus the documentation hook for the published
+recipe collection. No existing brick changes its numbers.
+
+### Added
+
+- **`subtract_bias`** (preprocessing, 1.0.0, numpy) — the zero-level correction of
+  standard CCD reduction (Howell 2006, *Handbook of CCD Astronomy*, ch. 4 ; Massey
+  1997, *A User's Guide to CCD Reductions with IRAF*) : `science − master_bias` in
+  float64 on `ctx.image`, master frame read from `ctx.extras['master_bias']` as written
+  by `bias_combine`, or a constant `bias_level` (overscan mean) when no bias frames
+  exist. No exposure-time scaling (a bias carries no dark current). Negative pixels are
+  kept unless `clip_negative=True` ; metrics `bias_median`, `median_after`,
+  `n_negative`, `n_clipped`. Native counterpart of `subtract_bias_easyspec`, which
+  AuroreX asked for after the BZERO staging bug of the easyspec wrappers (fixed in
+  0.2.1) : the native path never stages a FITS file. Tests : exact recovery of a
+  synthetic truth under a gradient bias, integer-ADU input, constant level, precedence
+  of `bias_level` over the frame, clipping count, three failure paths, chaining after
+  `bias_combine`.
+- `subtract_bias_easyspec` 1.0.1 → 1.0.2 : `long_description` cross-references the
+  native brick (docstring only).
+
+### Documentation
+
+- The `docs` extra now installs `spectro-kernel-recipes>=0.2.0` (published on PyPI on
+  2026-09-26), so the online recipe catalogue lists the ten campaign recipes next to the
+  seven bundled ones. No runtime change.
+
 ## [0.8.0] — 2026-09-26
 
 The "exactness" release : the four method corrections the September audit

{spectro_kernel-0.8.0 → spectro_kernel-0.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: spectro-kernel
-Version: 0.8.0
+Version: 0.8.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://docs.spectrokernel.io/
@@ -59,6 +59,7 @@ Requires-Dist: mkdocs-literate-nav>=0.6; extra == 'docs'
 Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
 Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
 Requires-Dist: pyyaml>=6.0; extra == 'docs'
+Requires-Dist: spectro-kernel-recipes>=0.2.0; extra == 'docs'
 Requires-Dist: zensical>=0.0.62; extra == 'docs'
 Provides-Extra: embedding-ml
 Requires-Dist: torch>=2.2; extra == 'embedding-ml'

{spectro_kernel-0.8.0 → spectro_kernel-0.8.1}/pyproject.toml

@@ -70,6 +70,7 @@ docs = [
   "mkdocs-literate-nav>=0.6",     # fallback engine's nav plugin (Zensical has it built in)
   "jsonschema>=4.0",              # validates docs/ai/algorithms.json at build time
   "pyyaml>=6.0",
+  "spectro-kernel-recipes>=0.2.0", # the campaign collection, so the online catalogue lists its recipes
 ]
 all = [
   "spectro-kernel[catalogs,viz,storage,reduction,mcp,monitoring,embedding-wavelets,embedding-remote]",

{spectro_kernel-0.8.0 → spectro_kernel-0.8.1}/src/spectro_kernel/algorithms/reduction/easyspec_subtract_bias.py

@@ -22,7 +22,7 @@ from ._easyspec_helpers import easyspec_session, silent_easyspec
 @register_algorithm(
     "subtract_bias_easyspec",
     category=AlgorithmCategory.PREPROCESSING,
-    version="1.0.1",
+    version="1.0.2",
 )
 class SubtractBiasEasyspec(BaseAlgorithm):
     """Subtract a master bias from a single science frame via ``cleaning.debias``.
@@ -37,6 +37,11 @@ class SubtractBiasEasyspec(BaseAlgorithm):
     references = [
         "easyspec.cleaning.cleaning.debias.",
     ]
+    long_description = (
+        "Wrapper of easyspec's ``debias`` (temporary FITS staging, negative pixels "
+        "clipped to zero by default). ``subtract_bias`` is the native numpy counterpart: "
+        "same arithmetic on ``ctx.image`` in float64, no staging, no clipping unless asked."
+    )
     default_params = {
         "target_path": None,
         "master_bias_path": None,

spectro_kernel-0.8.1/src/spectro_kernel/algorithms/reduction/subtract_bias.py

@@ -0,0 +1,122 @@
+"""Algorithm: subtract a master bias (or a constant bias level) from the working image."""
+
+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, ImageFrame, WorkContext
+
+
+@register_algorithm("subtract_bias", category=AlgorithmCategory.PREPROCESSING, version="1.0.0")
+class SubtractBias(BaseAlgorithm):
+    """Subtract the master bias (or a constant bias level) from ``ctx.image``.
+
+    The zero-level correction of standard CCD reduction (Howell 2006, ch. 4):
+    ``science - master_bias`` pixel by pixel, in float64, with no exposure-time
+    scaling (a bias frame carries no dark current). The master bias is read from
+    ``ctx.extras['master_bias']`` as written by ``bias_combine``; a constant
+    ``bias_level`` (for instance the overscan mean) can be subtracted instead
+    when no bias frames were taken.
+    """
+
+    backend = "numpy"
+    references = [
+        "Howell 2006 — Handbook of CCD Astronomy, 2nd ed., ch. 4 (bias frames, zero level).",
+        "Massey 1997 — A User's Guide to CCD Reductions with IRAF (NOAO), zero-level correction.",
+    ]
+    long_description = (
+        "Native counterpart of ``subtract_bias_easyspec``: the same arithmetic without the "
+        "easyspec staging (no temporary FITS, no clipping unless ``clip_negative`` is set), "
+        "so integer-ADU frames and BZERO-scaled files are handled in float64 end to end. "
+        "Precedence: an explicit ``bias_level`` wins over the master frame stored in "
+        "``ctx.extras[bias_key]``; with neither available the brick fails. Negative pixels "
+        "are kept by default because clipping biases the sky statistics of faint frames; "
+        "``clip_negative=True`` reproduces the easyspec ``pad_with_zeros`` behaviour. "
+        "Companion of ``dark_subtract`` (which scales by exposure time) and "
+        "``flat_normalize``."
+    )
+    default_params = {"bias_key": "master_bias", "bias_level": None, "clip_negative": False}
+    param_descriptions = {
+        "bias_key": "Key in ctx.extras where the master bias (an ImageFrame) is stored.",
+        "bias_level": (
+            "Constant bias level in ADU to subtract instead of a master frame "
+            "(e.g. the overscan mean); takes precedence over the master frame when set."
+        ),
+        "clip_negative": "Set the pixels that become negative after subtraction to zero.",
+    }
+    input_requirements = ["image"]
+    output_produces = [
+        "image",
+        "metrics.bias_median",
+        "metrics.median_after",
+        "metrics.n_negative",
+        "metrics.n_clipped",
+    ]
+
+    def run(self, ctx: WorkContext, params: dict[str, Any]) -> AlgorithmOutput:
+        image = ctx.image
+        if image is None:
+            return AlgorithmOutput.fail("subtract_bias: no image in the WorkContext.")
+
+        level = params.get("bias_level")
+        key = str(params["bias_key"])
+        if level is not None:
+            try:
+                level = float(level)
+            except (TypeError, ValueError) as exc:
+                raise InvalidParameterError(
+                    f"bias_level must be a number in ADU, got {level!r}."
+                ) from exc
+            if not math.isfinite(level):
+                raise InvalidParameterError("bias_level must be finite.")
+            bias: np.ndarray | float = level
+            source = "constant"
+            bias_median = level
+        else:
+            master = ctx.extras.get(key)
+            if not isinstance(master, ImageFrame):
+                return AlgorithmOutput.fail(
+                    f"No master bias in ctx.extras[{key!r}] and no bias_level given; "
+                    "run bias_combine on the bias frames first."
+                )
+            if master.data.shape != image.data.shape:
+                return AlgorithmOutput.fail(
+                    f"Shape mismatch: science {image.data.shape} "
+                    f"vs master bias {master.data.shape}."
+                )
+            bias = master.data.astype(np.float64)
+            source = f"extras[{key}]"
+            bias_median = float(np.nanmedian(master.data))
+
+        data = image.data.astype(np.float64) - bias
+        n_negative = int(np.count_nonzero(data < 0))
+        n_clipped = 0
+        if bool(params["clip_negative"]):
+            n_clipped = n_negative
+            data = np.where(data < 0, 0.0, data)
+
+        out = image.copy()
+        out.data = data
+        out.meta["bias_subtracted"] = True
+        out.meta["bias_source"] = source
+        out.meta["bias_median"] = bias_median
+        ctx.image = out
+        return AlgorithmOutput.ok(
+            metrics={
+                "bias_median": bias_median,
+                "median_after": float(np.nanmedian(data)),
+                "n_negative": n_negative,
+                "n_clipped": n_clipped,
+            },
+            message=(
+                f"Bias subtracted from {source} (median level {bias_median:.2f} ADU"
+                + (f", {n_clipped} negative pixels clipped to 0" if n_clipped else "")
+                + ")."
+            ),
+        )

{spectro_kernel-0.8.0 → spectro_kernel-0.8.1}/src/spectro_kernel/version.py

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

spectro_kernel-0.8.1/tests/unit/test_subtract_bias.py

@@ -0,0 +1,172 @@
+"""Tests for the native ``subtract_bias`` brick (Howell 2006, ch. 4 zero-level correction).
+
+The right answer is analytic: a science frame built as ``truth + bias`` must give
+back ``truth`` exactly once the same bias is subtracted (pure float64 arithmetic,
+no scaling, no clipping), whatever the input dtype.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pytest
+
+from spectro_kernel import WorkContext, run_algorithm
+from spectro_kernel.types import ImageFrame
+
+SHAPE = (8, 16)
+
+
+def _gradient_bias() -> np.ndarray:
+    rows, cols = SHAPE
+    # A pedestal of 300 ADU with a mild column gradient, as a real bias structure.
+    return 300.0 + np.linspace(0.0, 4.0, cols)[None, :] * np.ones((rows, 1))
+
+
+def _truth() -> np.ndarray:
+    rng = np.random.default_rng(0)
+    return rng.uniform(50.0, 5000.0, size=SHAPE)
+
+
+def test_master_frame_recovers_truth_exactly():
+    truth, bias = _truth(), _gradient_bias()
+    ctx = WorkContext(image=ImageFrame(data=truth + bias, frame_type="science"))
+    ctx.extras["master_bias"] = ImageFrame(data=bias, frame_type="bias")
+
+    out = run_algorithm("subtract_bias", ctx)
+
+    assert out.success
+    np.testing.assert_allclose(ctx.image.data, truth, rtol=0, atol=1e-9)
+    assert ctx.image.data.dtype == np.float64
+    assert ctx.image.meta["bias_subtracted"] is True
+    assert ctx.image.meta["bias_source"] == "extras[master_bias]"
+    assert out.metrics["bias_median"] == pytest.approx(float(np.median(bias)))
+    assert out.metrics["median_after"] == pytest.approx(float(np.median(truth)))
+    assert out.metrics["n_negative"] == 0
+    assert out.metrics["n_clipped"] == 0
+    # The input frame is not modified in place.
+    assert ctx.image is not None
+
+
+def test_integer_adu_input_does_not_wrap():
+    # A 16-bit camera frame below the bias level in places: uint16 arithmetic would wrap.
+    science = np.full(SHAPE, 1000, dtype=np.uint16)
+    bias = np.full(SHAPE, 1010.0)
+    ctx = WorkContext(image=ImageFrame(data=science, frame_type="science"))
+    ctx.extras["master_bias"] = ImageFrame(data=bias, frame_type="bias")
+
+    out = run_algorithm("subtract_bias", ctx)
+
+    assert out.success
+    np.testing.assert_allclose(ctx.image.data, -10.0)
+    assert out.metrics["n_negative"] == science.size
+    assert out.metrics["n_clipped"] == 0
+
+
+def test_constant_level_when_no_master_frame():
+    truth = _truth()
+    ctx = WorkContext(image=ImageFrame(data=truth + 250.5, frame_type="science"))
+
+    out = run_algorithm("subtract_bias", ctx, {"bias_level": 250.5})
+
+    assert out.success
+    np.testing.assert_allclose(ctx.image.data, truth, rtol=0, atol=1e-9)
+    assert ctx.image.meta["bias_source"] == "constant"
+    assert out.metrics["bias_median"] == pytest.approx(250.5)
+
+
+def test_explicit_level_takes_precedence_over_master_frame():
+    truth = _truth()
+    ctx = WorkContext(image=ImageFrame(data=truth + 100.0, frame_type="science"))
+    ctx.extras["master_bias"] = ImageFrame(data=np.full(SHAPE, 999.0), frame_type="bias")
+
+    out = run_algorithm("subtract_bias", ctx, {"bias_level": "100"})  # CLI-style string
+
+    assert out.success
+    np.testing.assert_allclose(ctx.image.data, truth, rtol=0, atol=1e-9)
+    assert ctx.image.meta["bias_source"] == "constant"
+
+
+def test_clip_negative_zeroes_and_counts():
+    science = np.array([[5.0, 20.0, 30.0], [40.0, 3.0, 60.0]])
+    ctx = WorkContext(image=ImageFrame(data=science, frame_type="science"))
+
+    out = run_algorithm("subtract_bias", ctx, {"bias_level": 10.0, "clip_negative": True})
+
+    assert out.success
+    np.testing.assert_allclose(ctx.image.data, [[0.0, 10.0, 20.0], [30.0, 0.0, 50.0]])
+    assert out.metrics["n_negative"] == 2
+    assert out.metrics["n_clipped"] == 2
+    assert "2 negative pixels clipped" in out.message
+
+
+def test_no_scaling_by_exposure_time():
+    # Unlike dark_subtract, EXPTIME must be ignored: a bias carries no dark current.
+    truth, bias = _truth(), _gradient_bias()
+    ctx = WorkContext(
+        image=ImageFrame(data=truth + bias, header={"EXPTIME": 600.0}, frame_type="science")
+    )
+    ctx.extras["master_bias"] = ImageFrame(data=bias, header={"EXPTIME": 0.0}, frame_type="bias")
+
+    out = run_algorithm("subtract_bias", ctx)
+
+    assert out.success
+    np.testing.assert_allclose(ctx.image.data, truth, rtol=0, atol=1e-9)
+
+
+def test_chains_after_bias_combine():
+    truth = _truth()
+    rng = np.random.default_rng(1)
+    bias_frames = [
+        ImageFrame(data=300.0 + rng.normal(0.0, 2.0, size=SHAPE), frame_type="bias")
+        for _ in range(5)
+    ]
+    master = np.median(np.stack([f.data for f in bias_frames]), axis=0)
+    ctx = WorkContext(images=bias_frames, image=ImageFrame(data=truth + master))
+
+    assert run_algorithm("bias_combine", ctx, {"method": "median"}).success
+    out = run_algorithm("subtract_bias", ctx)
+
+    assert out.success
+    np.testing.assert_allclose(ctx.image.data, truth, rtol=0, atol=1e-9)
+    assert [s.algorithm for s in ctx.history] == ["bias_combine", "subtract_bias"]
+    assert ctx.history[-1].success
+
+
+def test_fails_without_master_frame_or_level():
+    ctx = WorkContext(image=ImageFrame(data=_truth()))
+    out = run_algorithm("subtract_bias", ctx, raise_on_error=False)
+    assert not out.success
+    assert "bias_combine" in out.error
+    assert ctx.history[-1].success is False
+
+
+def test_fails_on_shape_mismatch():
+    ctx = WorkContext(image=ImageFrame(data=_truth()))
+    ctx.extras["master_bias"] = ImageFrame(data=np.zeros((4, 4)), frame_type="bias")
+    out = run_algorithm("subtract_bias", ctx, raise_on_error=False)
+    assert not out.success
+    assert "Shape mismatch" in out.error
+
+
+def test_fails_without_image_and_on_bad_level():
+    out = run_algorithm("subtract_bias", WorkContext(), raise_on_error=False)
+    assert not out.success
+
+    ctx = WorkContext(image=ImageFrame(data=_truth()))
+    out = run_algorithm("subtract_bias", ctx, {"bias_level": "overscan"}, raise_on_error=False)
+    assert not out.success
+    assert "bias_level" in out.error
+
+    out = run_algorithm("subtract_bias", ctx, {"bias_level": float("nan")}, raise_on_error=False)
+    assert not out.success
+    assert "finite" in out.error
+
+
+def test_custom_extras_key():
+    truth, bias = _truth(), _gradient_bias()
+    ctx = WorkContext(image=ImageFrame(data=truth + bias))
+    ctx.extras["zero"] = ImageFrame(data=bias, frame_type="bias")
+    out = run_algorithm("subtract_bias", ctx, {"bias_key": "zero"})
+    assert out.success
+    np.testing.assert_allclose(ctx.image.data, truth, rtol=0, atol=1e-9)
+    assert ctx.image.meta["bias_source"] == "extras[zero]"