pyobs-core 2.1.0__tar.gz → 2.2.0__tar.gz

{pyobs_core-2.1.0 → pyobs_core-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pyobs-core
-Version: 2.1.0
+Version: 2.2.0
 Summary: robotic telescope software
 Author-email: Tim-Oliver Husser <thusser@uni-goettingen.de>
 License-Expression: MIT

pyobs_core-2.2.0/pyobs/images/processors/calibration/_calibration_cache.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from collections import deque
+from typing import cast
+
+from pyobs.images import Image
+from pyobs.utils.enums import ImageType
+
+
+class _CalibrationCache:
+    BINNING_FORMAT = "{0}x{0}"
+
+    def __init__(self, max_size: int):
+        self._cache: deque[tuple[tuple[ImageType, str, str, str | None, float | None], Image]] = deque([], max_size)
+
+    def add_to_cache(self, image: Image, image_type: ImageType, exptime: float | None = None) -> None:
+        cache_keys = self._get_cache_keys(image, image_type, exptime)
+        cache_entry = (cache_keys, image)
+        self._cache.append(cache_entry)
+
+    def get_from_cache(self, image: Image, image_type: ImageType, exptime: float | None = None) -> Image:
+        cache_keys = self._get_cache_keys(image, image_type, exptime)
+        return self._find_cache_entry(cache_keys)
+
+    def _find_cache_entry(self, keys: tuple[ImageType, str, str, str | None, float | None]) -> Image:
+        for m, item in self._cache:
+            if m == keys:
+                return item
+
+        raise ValueError("Calibration not found in cache.")
+
+    def _get_cache_keys(
+        self, image: Image, image_type: ImageType, exptime: float | None = None
+    ) -> tuple[ImageType, str, str, str | None, float | None]:
+        instrument, binning, filter_name = self._get_image_cache_keys(image)
+        if image_type in (ImageType.BIAS, ImageType.DARK):
+            # BIAS/DARK lookups ignore filter (matching Calibration._find_master_in_archive,
+            # which never passes a science image's FILTER to Pipeline.find_master for these two
+            # types). Deriving filter_name from whichever image was passed -- the science image
+            # on a get, the master on an add -- would otherwise near-guarantee a cache miss:
+            # a master dark/bias frequently has no FILTER header at all (or a stale one from
+            # whatever was mounted at the time) while the science image usually does.
+            filter_name = None
+        # exptime is not derived from `image`'s own header: for DARK, callers pass the exptime
+        # they searched for (the science exptime for an exact match, or the configured
+        # reference exptime for a scale-down lookup), which generally differs from either the
+        # science image's or the master's own EXPTIME. None for BIAS/SKYFLAT, unchanged.
+        cache_keys = (image_type, instrument, binning, filter_name, exptime)
+
+        return cache_keys
+
+    def _get_image_cache_keys(self, image: Image) -> tuple[str, str, str | None]:
+        instrument = image.header["INSTRUME"]
+        binning = self.BINNING_FORMAT.format(image.header["XBINNING"])  # noqa: UP031
+
+        filter_name = None
+        if "FILTER" in image.header:
+            filter_name = cast(str, image.header["FILTER"])
+
+        return instrument, binning, filter_name

{pyobs_core-2.1.0 → pyobs_core-2.2.0}/pyobs/images/processors/calibration/_ccddata_calibrator.py

@@ -7,7 +7,14 @@ from pyobs.images import Image
 
 
 class _CCDDataCalibrator:
-    def __init__(self, image: Image, bias: Image | None = None, dark: Image | None = None, flat: Image | None = None):
+    def __init__(
+        self,
+        image: Image,
+        bias: Image | None = None,
+        dark: Image | None = None,
+        flat: Image | None = None,
+        dark_scale: bool = True,
+    ):
         # to_ccddata() below never carries a catalog through anyway, so drop it before trim() to
         # avoid its stale-catalog guard rejecting an image whose catalog wouldn't survive regardless.
         if image.safe_catalog is not None:
@@ -17,10 +24,16 @@ class _CCDDataCalibrator:
         self._bias = self._optional_to_ccddata(bias)
         self._dark = self._optional_to_ccddata(dark)
         self._flat = self._optional_to_ccddata(flat)
+        # whether ccd_process() should rescale the dark to the science exptime -- False for an
+        # exact exptime-match master, which is used as-is (see Calibration._find_dark_master).
+        self._dark_scale = dark_scale
 
         self._ccd_data = self._image.to_ccddata()
 
-        if dark is not None:
+        # only read EXPTIME when it's actually needed -- an unscaled exact-match dark
+        # (dark_scale=False) doesn't require it, and a legacy master combined from raw frames
+        # with no EXPTIME at all (see Reduction._create_master_darks' fallback) doesn't have it
+        if dark is not None and dark_scale:
             self._dark_exp_time = dark.header["EXPTIME"]
 
     @staticmethod
@@ -47,8 +60,8 @@ class _CCDDataCalibrator:
             bad_pixel_mask=None,
             gain=self._image.header["DET-GAIN"] * u.electron / u.adu,
             readnoise=self._image.header["DET-RON"] * u.electron,
-            dark_exposure=self._dark_exp_time * u.second if self._dark is not None else None,
+            dark_exposure=self._dark_exp_time * u.second if (self._dark is not None and self._dark_scale) else None,
             data_exposure=self._image.header["EXPTIME"] * u.second,
-            dark_scale=True,
+            dark_scale=self._dark_scale,
             gain_corrected=False,
         )

pyobs_core-2.2.0/pyobs/images/processors/calibration/calibration.py

@@ -0,0 +1,513 @@
+from __future__ import annotations
+
+import logging
+from typing import Any, cast
+
+import astropy.units as u
+
+from pyobs.images import Image
+from pyobs.images.processor import ImageProcessor
+from pyobs.images.processors.calibration._calibration_cache import _CalibrationCache
+from pyobs.images.processors.calibration._ccddata_calibrator import _CCDDataCalibrator
+from pyobs.robotic.utils.archive import Archive
+from pyobs.utils.enums import ImageType
+from pyobs.utils.exptime_grouping import exptimes_close
+from pyobs.utils.pipeline import Pipeline
+from pyobs.utils.time import Time
+
+log = logging.getLogger(__name__)
+
+
+class Calibration(ImageProcessor):
+    """
+    Calibrate an image using master bias, dark, and flat frames fetched from an archive.
+
+    This processor locates appropriate master calibration frames
+    (bias, dark, flat) based on the input image metadata, applies calibration to the
+    image, and annotates the FITS header with provenance and reduction information.
+    Calibration frames are looked up via an :class:`~pyobs.robotic.utils.archive.Archive` and are
+    cached in a class-wide cache to reduce repeated lookups. If required calibration
+    frames cannot be found, the original image is returned unchanged.
+
+    :param dict | Archive archive: Archive configuration or an already constructed
+                                  :class:`~pyobs.robotic.utils.archive.Archive` instance used to
+                                  locate master calibration frames. If a dictionary
+                                  is provided, it is instantiated via
+                                  :func:`~pyobs.object.get_object`.
+    :param int max_cache_size: Maximum number of master frames kept in the shared
+                               calibration cache. Default: ``20``.
+    :param bool require_bias: If ``True``, a master bias must be found; otherwise
+                              calibration is aborted and the image is returned
+                              unchanged. If ``False``, bias subtraction is skipped.
+                              Default: ``True``.
+    :param bool require_dark: If ``True``, a master dark must be found; otherwise
+                              calibration is aborted. If ``False``, dark subtraction
+                              is skipped. Default: ``True``.
+    :param bool require_flat: If ``True``, a master flat must be found; otherwise
+                              calibration is aborted. If ``False``, flat-fielding is
+                              skipped. Default: ``True``.
+    :param float | None max_days_bias: Maximum age difference in days allowed when
+                                       selecting the master bias relative to the
+                                       science image ``DATE-OBS``. If ``None``, no
+                                       explicit age limit is applied. Default: ``None``.
+    :param float | None max_days_dark: Same as ``max_days_bias`` for dark frames.
+                                       Default: ``None``.
+    :param float | None max_days_flat: Same as ``max_days_bias`` for flat frames.
+                                       Default: ``None``.
+    :param float dark_exptime_tolerance: Relative tolerance for matching a science frame's
+                                         ``EXPTIME`` against a dark master's, and for the
+                                         scale-down-only ceiling around ``dark_scale_exptime``.
+                                         Default: ``0.01`` (1%).
+    :param float | None dark_scale_exptime: Reference dark exposure time (seconds) that may be
+                                            scaled down to a shorter science exptime when no
+                                            exact-exptime master exists. ``None`` disables
+                                            scale-down entirely (branch 3 below never fires).
+                                            Default: ``600.0``.
+    :param bool allow_unmatched_dark_scale: If ``True``, a science exptime with neither an
+                                            exact-match master nor a usable reference master
+                                            falls back to today's always-scale-whatever-is-
+                                            nearest behavior instead of raising. For sites not
+                                            yet taking per-exptime darks. Default: ``False``.
+    :param float | None dark_min_exptime: Science exptimes below this (and with no exact-match
+                                          master) skip dark subtraction entirely and are
+                                          calibrated with bias only -- dark current is assumed
+                                          negligible there. ``None`` or ``0`` disables this
+                                          branch. Default: ``5.0``.
+    :param kwargs: Additional keyword arguments forwarded to
+                   :class:`pyobs.images.processor.ImageProcessor`.
+
+    Behavior
+    --------
+    - Verifies required image header keys before searching: ``INSTRUME``, ``XBINNING``,
+      and ``DATE-OBS`` must be present.
+    - Attempts to retrieve required masters (bias, dark, flat) from a class-wide cache.
+      On cache miss, queries the configured archive via
+      :meth:`~pyobs.utils.pipeline.Pipeline.find_master`, matching:
+
+      - Instrument: exact value of ``INSTRUME``.
+      - Binning: string formatted as ``"{XBINNING}x{XBINNING}"`` (square binning assumed).
+      - Filter: ``FILTER`` only for flats; biases and darks ignore filter.
+      - Time constraint: centered on the image ``DATE-OBS`` with optional ``max_days_*``.
+
+    - Dark matching additionally follows ADR
+      ``0015-dark-master-strict-exptime-matching-reference-scale-down-only.md``, checked in
+      order against the science frame's own ``EXPTIME``:
+
+      1. An exact match (within ``dark_exptime_tolerance``) is used unscaled.
+      2. No exact match and ``EXPTIME < dark_min_exptime``: bias-only, no dark subtraction,
+         not an error.
+      3. No exact match, ``EXPTIME >= dark_min_exptime``, and a reference master with
+         ``EXPTIME <= dark_scale_exptime`` exists: used scaled down to the science exptime.
+      4. ``allow_unmatched_dark_scale=True``: fall back to whatever ``find_master`` returns,
+         scaled, regardless of direction (today's behavior).
+      5. Otherwise: a ``ValueError`` naming the requested exptime, caught the same way as any
+         other missing-master case (see below).
+
+    - If any required master is missing, logs a warning and returns the original image
+      unchanged.
+    - Applies calibration using the internal ``_CCDDataCalibrator`` helper
+      with the found master frames (``None`` for any non-required step to be skipped).
+    - Copies provenance into the output FITS header:
+
+      - ``L1RAW`` set from the original ``ORIGNAME`` (file stem without ``.fits``).
+      - ``L1BIAS``, ``L1DARK``, ``L1FLAT`` set from the respective master frame
+        ``FNAME`` values (with common FITS extensions removed) and descriptive comments.
+
+    - Sets calibration metadata in the output header:
+
+      - ``BUNIT = "electron"`` to indicate calibrated pixel units.
+      - ``RLEVEL = 1`` to indicate reduction level.
+
+    Input/Output
+    ------------
+    - Input: :class:`pyobs.images.Image` with FITS header containing at least
+      ``INSTRUME``, ``XBINNING``, and ``DATE-OBS``; optional ``FILTER`` improves flat matching.
+    - Output: :class:`pyobs.images.Image` calibrated by subtracting bias, subtracting
+      dark, and dividing by flat as available. Pixel data are modified; header is
+      augmented with provenance and reduction keys.
+
+    Configuration (YAML)
+    --------------------
+    Use an archive object and allow calibration frames up to 7 days old:
+
+    .. code-block:: yaml
+
+       class: pyobs.images.processors.calibration.Calibration
+       archive:
+         class: your.archive.Class  # replace with your Archive implementation
+         # ... archive-specific configuration ...
+       max_cache_size: 50
+       max_days_bias: 7
+       max_days_dark: 7
+       max_days_flat: 7
+       require_bias: true
+       require_dark: true
+       require_flat: true
+
+    Skip flats but require bias and dark:
+
+    .. code-block:: yaml
+
+       class: pyobs.images.processors.calibration.Calibration
+       archive: { class: your.archive.Class, ... }
+       require_flat: false
+
+    Notes
+    -----
+    - The calibration cache is shared across all instances of this class within the
+      process and is bounded by ``max_cache_size``.
+    - Only ``XBINNING`` is considered; this implementation assumes square binning.
+      If your data use asymmetric binning, adjust the matching logic.
+    - Flats are matched by filter when available; biases and darks ignore filter.
+    - If ``ORIGNAME`` is present in the input header, it is copied to ``L1RAW`` as a
+      stem without the ``.fits`` suffix. Master frame names are copied from ``FNAME``.
+    - Setting ``BUNIT = "electron"`` assumes calibrated units are electrons; ensure
+      your calibration products and gains are consistent with this convention.
+    """
+
+    __module__ = "pyobs.images.processors.calibration"
+
+    """Cache for calibration frames."""
+    _calib_cache: _CalibrationCache | None = None
+
+    def __init__(
+        self,
+        archive: dict[str, Any] | Archive,
+        max_cache_size: int = 20,
+        require_bias: bool = True,
+        require_dark: bool = True,
+        require_flat: bool = True,
+        max_days_bias: float | None = None,
+        max_days_dark: float | None = None,
+        max_days_flat: float | None = None,
+        dark_exptime_tolerance: float = 0.01,
+        dark_scale_exptime: float | None = 600.0,
+        allow_unmatched_dark_scale: bool = False,
+        dark_min_exptime: float | None = 5.0,
+        **kwargs: Any,
+    ):
+        """Init a new image calibration pipeline step.
+
+        Args:
+            archive: Archive to fetch calibration frames from.
+        """
+        ImageProcessor.__init__(self, **kwargs)
+
+        self._max_cache_size = max_cache_size
+        self._max_days_bias = max_days_bias
+        self._max_days_dark = max_days_dark
+        self._max_days_flat = max_days_flat
+        self._require_bias = require_bias
+        self._require_dark = require_dark
+        self._require_flat = require_flat
+        self._dark_exptime_tolerance = dark_exptime_tolerance
+        self._dark_scale_exptime = dark_scale_exptime
+        self._allow_unmatched_dark_scale = allow_unmatched_dark_scale
+        self._dark_min_exptime = dark_min_exptime
+
+        self._archive = self.pyobs_model_validate(Archive, archive)
+
+        if self._calib_cache is None:
+            self._calib_cache = _CalibrationCache(self._max_cache_size)
+
+    async def __call__(self, image: Image) -> Image:
+        """Calibrate an image.
+
+        Args:
+            image: Image to calibrate.
+
+        Returns:
+            Calibrated image.
+        """
+
+        try:
+            bias, dark, flat, dark_scale = await self._get_calibrations_masters(image)
+        except ValueError as e:
+            log.warning("Could not find calibration frames: %s", e)
+            return image
+
+        calibrator = _CCDDataCalibrator(image, bias, dark, flat, dark_scale=dark_scale)
+        calibrated = calibrator()
+
+        self._copy_original_filename(calibrated, image)
+        self._copy_calibration_filename(calibrated, bias, dark, flat)
+
+        self._set_calibration_headers(calibrated)
+
+        return calibrated
+
+    async def _get_calibrations_masters(self, image: Image) -> tuple[Image | None, Image | None, Image | None, bool]:
+        bias = (
+            None
+            if not self._require_bias
+            else await self._find_master(image, ImageType.BIAS, max_days=self._max_days_bias)
+        )
+        dark, dark_scale = await self._find_dark_master(image)
+        flat = (
+            None
+            if not self._require_flat
+            else await self._find_master(image, ImageType.SKYFLAT, max_days=self._max_days_flat)
+        )
+
+        return bias, dark, flat, dark_scale
+
+    async def _find_dark_master(self, image: Image) -> tuple[Image | None, bool]:
+        """Implements ADR 0015's dark-master matching/scaling policy, checked in order against
+        the science image's own EXPTIME:
+
+        1. An exact match (within dark_exptime_tolerance) -- used unscaled.
+        2. No exact match and EXPTIME < dark_min_exptime -- bias-only, not an error.
+        3. No exact match, EXPTIME >= dark_min_exptime, and a reference master with
+           EXPTIME <= dark_scale_exptime *and* EXPTIME >= science_exptime exists -- used
+           scaled down to the science exptime. The second condition is what actually
+           enforces "scaled down only": without it, a site whose longest master happens to be
+           shorter than the science exptime would otherwise get that master scaled *up*.
+        4. allow_unmatched_dark_scale=True -- fall back to today's always-scale-whatever-is-
+           nearest behavior. A candidate with no EXPTIME at all (a legacy master) can't be
+           scaled either way, so it's used unscaled (dark_scale=False) rather than skipped.
+        5. Otherwise -- ValueError, caught by __call__ like any other missing-master case.
+
+        Returns:
+            (master, scale). master is None only for the legitimate bias-only branch (2), or
+            when require_dark is False. scale tells the caller whether _CCDDataCalibrator
+            should rescale the returned master to the science exptime.
+
+        Raises:
+            ValueError: no usable dark master under the configured policy (branch 5).
+        """
+        if not self._require_dark:
+            return None, False
+
+        self._verify_image_header(image)
+        science_exptime = float(image.header["EXPTIME"])
+
+        # (1) exact match, used unscaled
+        exact = await self._find_dark_at(image, science_exptime, self._max_days_dark)
+        if exact is not None:
+            return exact, False
+
+        # (2) below the minimum, no exact match -- bias-only, not an error
+        if self._dark_min_exptime is not None and science_exptime < self._dark_min_exptime:
+            return None, False
+
+        # (3) reference master, scaled down only (never up). exptime_max=dark_scale_exptime only
+        # bounds the reference search from above; a site with no master anywhere near
+        # dark_scale_exptime (e.g. only a 45s one) could otherwise get that shorter master back
+        # as the "reference" and have it scaled UP to a longer science exptime -- exactly the
+        # direction ADR 0015 forbids. Guard against that explicitly: reject a candidate whose
+        # own exptime doesn't cover science_exptime (within tolerance), falling through instead.
+        if self._dark_scale_exptime is not None and science_exptime <= self._dark_scale_exptime * (
+            1 + self._dark_exptime_tolerance
+        ):
+            reference = await self._find_dark_at(
+                image, self._dark_scale_exptime, self._max_days_dark, exptime_max=self._dark_scale_exptime
+            )
+            if reference is not None and self._covers_scale_down(reference, science_exptime):
+                return reference, True
+
+        # (4) opt back into today's always-scale-whatever-is-nearest behavior
+        if self._allow_unmatched_dark_scale:
+            fallback = await self._find_master(image, ImageType.DARK, max_days=self._max_days_dark)
+            # a legacy master with no EXPTIME at all can't be scaled -- ccd_process needs the
+            # dark's own exposure time to compute the scale factor (see _CCDDataCalibrator)
+            return fallback, "EXPTIME" in fallback.header
+
+        # (5) strict -- no usable dark master under the configured policy
+        ceiling = (
+            None if self._dark_scale_exptime is None else self._dark_scale_exptime * (1 + self._dark_exptime_tolerance)
+        )
+        available = await self._available_dark_exptimes(image)
+        raise ValueError(
+            f"No usable dark master for EXPTIME={science_exptime}s (no exact match within "
+            f"{self._dark_exptime_tolerance:.0%}"
+            + (
+                f", no reference master <= {ceiling:.1f}s to scale down"
+                if ceiling is not None
+                else ", no reference exptime configured"
+            )
+            + f"); available master exptimes: {available if available else 'none'}."
+        )
+
+    def _covers_scale_down(self, reference: Image, science_exptime: float) -> bool:
+        """Whether `reference`'s own exptime is long enough to be scaled *down* to
+        science_exptime -- ADR 0015 forbids the reverse. False (not usable as a reference) for
+        a master shorter than science_exptime, or one with no EXPTIME to check at all (a legacy
+        master -- direction can't be verified, so it's rejected rather than assumed safe)."""
+        if "EXPTIME" not in reference.header:
+            return False
+        return float(reference.header["EXPTIME"]) >= science_exptime * (1 - self._dark_exptime_tolerance)
+
+    async def _available_dark_exptimes(self, image: Image) -> list[float]:
+        """Best-effort list of exptimes among this instrument/binning's archived DARK masters
+        near the science image's DATE-OBS, for the strict-policy error message only (ADR 0015
+        asks that it name what's available). Bounded to max_days_dark (falling back to a wide
+        30-day window if unset) so this doesn't scan an archive's entire DARK history on every
+        strict-failure frame. Never raises -- an archive issue here shouldn't mask the real
+        ValueError being raised."""
+        try:
+            instrument = image.header["INSTRUME"]
+            binning = "{0}x{0}".format(image.header["XBINNING"])  # noqa: UP031
+            time = Time(image.header["DATE-OBS"])
+            max_days = self._max_days_dark if self._max_days_dark is not None else 30.0
+            infos = await self._archive.list_frames(
+                start=time - max_days * u.day,
+                end=time + max_days * u.day,
+                instrument=instrument,
+                image_type=ImageType.DARK,
+                binning=binning,
+                rlevel=1,
+            )
+        except Exception:
+            return []
+        return sorted({i.exptime for i in infos if i.exptime is not None})
+
+    async def _find_dark_at(
+        self, image: Image, target_exptime: float, max_days: float | None, exptime_max: float | None = None
+    ) -> Image | None:
+        """Looks up a DARK master near target_exptime via the shared calibration cache, keyed
+        by that target rather than either image's own EXPTIME (see _CalibrationCache), falling
+        back to an archive query on a cache miss.
+
+        Args:
+            target_exptime: Exptime to search near -- the science exptime for an exact-match
+                lookup, or dark_scale_exptime for a reference lookup.
+            exptime_max: If given, only accept candidates with EXPTIME <= this (scale-down-only
+                enforcement); the result is otherwise accepted whatever its exptime. If not
+                given, this is an exact-match lookup: the result is discarded (returns None)
+                unless it's actually within dark_exptime_tolerance of target_exptime.
+
+        Returns:
+            The master, or None if nothing usable was found. Never raises.
+        """
+        if self._calib_cache is None:
+            return None
+
+        try:
+            return self._calib_cache.get_from_cache(image, ImageType.DARK, exptime=target_exptime)
+        except ValueError:
+            pass
+
+        self._verify_image_header(image)
+        instrument = image.header["INSTRUME"]
+        binning = "{0}x{0}".format(image.header["XBINNING"])  # noqa: UP031
+        time = Time(image.header["DATE-OBS"])
+
+        master = await Pipeline.find_master(
+            self._archive,
+            ImageType.DARK,
+            time,
+            instrument,
+            binning,
+            None,
+            max_days=max_days,
+            exptime=target_exptime,
+            exptime_tolerance=self._dark_exptime_tolerance,
+            exptime_max=exptime_max,
+        )
+        if master is None:
+            return None
+
+        if exptime_max is None and (
+            "EXPTIME" not in master.header
+            or not exptimes_close(float(master.header["EXPTIME"]), target_exptime, self._dark_exptime_tolerance)
+        ):
+            # nearest available, but not actually an exact match (or a legacy pre-#831 master
+            # with no EXPTIME header at all) -- not usable for this lookup
+            return None
+
+        self._calib_cache.add_to_cache(master, ImageType.DARK, exptime=target_exptime)
+        return master
+
+    async def _find_master(self, image: Image, image_type: ImageType, max_days: float | None = None) -> Image:
+        """Find master calibration frame for given parameters using a cache.
+
+        Args:
+            image_type: image type.
+
+        Returns:
+            Image or None
+
+        Raises:
+            ValueError: if no calibration frame could be found.
+        """
+
+        self._verify_image_header(image)
+
+        if self._calib_cache is None:
+            raise ValueError("No cache.")
+
+        try:
+            return self._calib_cache.get_from_cache(image, image_type)
+        except ValueError:
+            master = await self._find_master_in_archive(image, image_type, max_days)
+            self._calib_cache.add_to_cache(master, image_type)
+            return master
+
+    @staticmethod
+    def _verify_image_header(image: Image) -> None:
+        has_instrument = "INSTRUME" in image.header
+        has_binning = "XBINNING" in image.header
+        has_time = "DATE-OBS" in image.header
+        # EXPTIME is needed by dark-exptime matching (_find_dark_master) and was already an
+        # implicit requirement of _CCDDataCalibrator itself (data_exposure=...EXPTIME...) --
+        # checked upfront here instead of surfacing as a bare KeyError mid-calibration.
+        has_exptime = "EXPTIME" in image.header
+
+        if not (has_instrument and has_binning and has_time and has_exptime):
+            raise ValueError("Could not fetch items from image header.")
+
+    async def _find_master_in_archive(
+        self, image: Image, image_type: ImageType, max_days: float | None = None
+    ) -> Image:
+        instrument = image.header["INSTRUME"]
+        binning = "{0}x{0}".format(image.header["XBINNING"])  # noqa: UP031
+        filter_name = cast(str, image.header["FILTER"]) if "FILTER" in image.header else None
+        time = Time(image.header["DATE-OBS"])
+
+        master = await Pipeline.find_master(
+            self._archive,
+            image_type,
+            time,
+            instrument,
+            binning,
+            None if image_type in [ImageType.BIAS, ImageType.DARK] else filter_name,
+            max_days=max_days,
+        )
+
+        if master is None:
+            raise ValueError("No master frame found.")
+
+        return master
+
+    @staticmethod
+    def _copy_original_filename(calibrated: Image, original: Image) -> None:
+        if "ORIGNAME" in original.header:
+            calibrated.header["L1RAW"] = original.header["ORIGNAME"].replace(".fits", "")
+
+    @staticmethod
+    def _copy_calibration_filename(
+        calibrated: Image, bias: Image | None = None, dark: Image | None = None, flat: Image | None = None
+    ) -> None:
+        if bias is not None:
+            calibrated.header["L1BIAS"] = (
+                bias.header["FNAME"].replace(".fits.fz", "").replace(".fits", ""),
+                "Name of BIAS frame",
+            )
+        if dark is not None:
+            calibrated.header["L1DARK"] = (
+                dark.header["FNAME"].replace(".fits.fz", "").replace(".fits", ""),
+                "Name of DARK frame",
+            )
+        if flat is not None:
+            calibrated.header["L1FLAT"] = (
+                flat.header["FNAME"].replace(".fits.fz", "").replace(".fits", ""),
+                "Name of FLAT frame",
+            )
+
+    @staticmethod
+    def _set_calibration_headers(calibrated: Image) -> None:
+        calibrated.header["BUNIT"] = ("electron", "Unit of pixel values")
+        calibrated.header["RLEVEL"] = (1, "Reduction level")
+
+
+__all__ = ["Calibration"]