tscp 0.1.0.dev0__py3-none-any.whl

tscp/scores/base.py

@@ -0,0 +1,87 @@
+"""The score interface (axis 2)."""
+
+import torch
+from torch import Tensor
+
+from tscp.data import ResidualArchive
+from tscp.regions import RESIDUAL_DIMS, Region
+from tscp.utils import Component
+
+
+class Score(Component):
+    """How an error becomes a number, and the region a threshold on it defines.
+
+    A score maps the rows of an archive to ``[T, *kept]``. The kept dimensions are the
+    dimensions of ``[H, N]`` it does not reduce, followed by one dimension for its
+    :attr:`channels` if it has any. A per-step score keeps step and series and yields an
+    interval per element. A score over the whole horizon reduces ``"step"`` and yields one
+    joint region per series; a score across series reduces ``"series"``. Weights, quantile
+    models and online updates treat each kept element as its own problem.
+
+    A score sees the whole rows: residuals, forecasts, forecaster outputs and context,
+    and, through the rows' timeline, the history before them. The region of a threshold
+    ``q`` is ``{r : score(r) <= q}``, so a target is missed exactly when its score exceeds
+    the threshold.
+
+    Channels split one element into several scores that are thresholded separately, such
+    as the lower and upper side of an interval. :meth:`levels` then shares the miscoverage
+    ``alpha`` among them so that the combined region still misses with probability at
+    most ``alpha``.
+    """
+
+    #: Dimensions of ``[H, N]`` this score reduces into one number.
+    reduce_dims: tuple[str, ...] = ()
+    #: Names of the channels, each thresholded separately; empty for one score per element.
+    channels: tuple[str, ...] = ()
+
+    def forward(self, rows: ResidualArchive) -> Tensor:
+        """Return scores of shape ``[T, *kept]`` for the ``T`` rows of ``rows``."""
+        raise NotImplementedError
+
+    def region(self, threshold: Tensor, rows: ResidualArchive) -> Region:
+        """Return the region ``{r : score(r) <= threshold}`` for each query row.
+
+        Args:
+            threshold: ``[Q, *kept]`` thresholds, one per query row and kept element.
+            rows: The ``Q`` query rows. Their forecasts, outputs and context are known at
+                their origins, so a region may use them; their residuals are not, and a
+                region must never read them.
+        """
+        raise NotImplementedError
+
+    def kept_shape(self, horizon: int, num_series: int) -> tuple[int, ...]:
+        """Return the sizes of the kept dimensions for an archive with ``H`` and ``N``."""
+        unknown = set(self.reduce_dims) - set(RESIDUAL_DIMS)
+        if unknown:
+            raise ValueError(f"reduce_dims may only name {RESIDUAL_DIMS}, not {sorted(unknown)}")
+        sizes = {"step": horizon, "series": num_series}
+        kept = tuple(size for name, size in sizes.items() if name not in self.reduce_dims)
+        return (*kept, len(self.channels)) if self.channels else kept
+
+    def levels(self, alpha: float, kept: tuple[int, ...]) -> Tensor:
+        """Return the miscoverage level of each kept element, ``[*kept]`` in float64.
+
+        By default every element gets ``alpha``. A score with channels overrides this to
+        share ``alpha`` among them.
+        """
+        return torch.full(kept, float(alpha), dtype=torch.float64)
+
+    def valid(self, rows: ResidualArchive) -> Tensor | None:
+        """Return which scores are defined, ``[T, *kept]`` bool, or None if all are.
+
+        A score is defined where every residual it combines is observed: its own element
+        for a per-step score, and every step or series it reduces otherwise. Channels
+        share the mask of their element.
+        """
+        observed = rows.observed
+        if observed is None or bool(observed.all()):
+            return None
+        reduced = tuple(1 + RESIDUAL_DIMS.index(name) for name in self.reduce_dims)
+        if reduced:
+            observed = observed.all(dim=reduced)
+        if self.channels:
+            observed = observed.unsqueeze(-1).expand(*observed.shape, len(self.channels))
+        return observed
+
+
+__all__ = ["Score"]

tscp/scores/cqr.py

@@ -0,0 +1,71 @@
+"""Conformalized quantile regression."""
+
+import torch
+from torch import Tensor
+
+from tscp.data import ResidualArchive
+from tscp.regions import Interval
+from tscp.registry import register
+from tscp.scores.base import Score
+
+
+@register("score", "cqr")
+class CQRScore(Score):
+    """Conformalized quantile regression (Romano, Patterson & Candès, NeurIPS 2019).
+
+    The forecaster supplies a lower and an upper quantile of each target, stored as
+    outputs in target units, as the forecaster produced them. In residual coordinates
+    they are ``low = q_lower - f`` and ``high = q_upper - f`` for the point forecast
+    ``f``, so the archive needs its ``forecasts``. The score ``max(low - r, r - high)`` is
+    how far the target falls outside the forecaster's band (negative inside it), and a
+    threshold ``q`` widens the band by ``q`` on both sides.
+
+    With ``asymmetric=True`` the two sides are channels at ``alpha / 2`` each, scored
+    ``low - r`` and ``r - high``, so each side gets its own correction (Romano et al.,
+    Theorem 2).
+
+    Args:
+        lower: Name of the output with the lower quantiles, ``[T, H, N]``.
+        upper: Name of the output with the upper quantiles, ``[T, H, N]``.
+        asymmetric: Correct each side separately.
+    """
+
+    def __init__(self, lower: str = "lower", upper: str = "upper", asymmetric: bool = False):
+        super().__init__()
+        self.lower = lower
+        self.upper = upper
+        self.asymmetric = bool(asymmetric)
+        self.channels = ("lower", "upper") if self.asymmetric else ()
+
+    def _band(self, rows: ResidualArchive) -> tuple[Tensor, Tensor]:
+        """The forecaster's band in residual coordinates: ``(low, high)``, each ``[T, H, N]``."""
+        if rows.forecasts is None:
+            raise ValueError("CQRScore needs the archive's forecasts")
+        missing = [name for name in (self.lower, self.upper) if name not in rows.outputs]
+        if missing:
+            raise KeyError(f"the archive has no outputs {missing}")
+        bounds = (rows.outputs[self.lower], rows.outputs[self.upper])
+        if any(bound.shape != rows.residuals.shape for bound in bounds):
+            raise ValueError("quantile outputs must have shape [T, H, N]")
+        return bounds[0] - rows.forecasts, bounds[1] - rows.forecasts
+
+    def forward(self, rows: ResidualArchive) -> Tensor:
+        low, high = self._band(rows)
+        below, above = low - rows.residuals, rows.residuals - high
+        if self.asymmetric:
+            return torch.stack([below, above], dim=-1)
+        return torch.maximum(below, above)
+
+    def region(self, threshold: Tensor, rows: ResidualArchive) -> Interval:
+        low, high = self._band(rows)
+        if self.asymmetric:
+            return Interval(low - threshold[..., 0], high + threshold[..., 1])
+        return Interval(low - threshold, high + threshold)
+
+    def levels(self, alpha: float, kept: tuple[int, ...]) -> Tensor:
+        if self.asymmetric:
+            return torch.full(kept, float(alpha) / 2, dtype=torch.float64)
+        return super().levels(alpha, kept)
+
+
+__all__ = ["CQRScore"]

tscp/scores/normalized.py

@@ -0,0 +1,74 @@
+"""Residuals divided by their expected size."""
+
+from typing import Self
+
+import torch
+from torch import Tensor
+
+from tscp.data import ResidualArchive
+from tscp.regions import Interval
+from tscp.registry import register
+from tscp.scores.base import Score
+
+
+@register("score", "normalized")
+class NormalizedScore(Score):
+    """``|r| / scale``: each error in units of its expected size.
+
+    The scale comes either from the forecaster, as an output with a predicted spread per
+    target (``scale="name"``), or from the fit split (``scale=None``): the root mean
+    square of the observed residuals of each step and series. A threshold ``q`` gives the
+    interval ``[-q * scale, q * scale]``, so regions widen where errors are expected to be
+    large.
+
+    Args:
+        scale: Name of a forecaster output of shape ``[T, H, N]`` with positive scales,
+            or None to fit one scale per step and series on the fit split.
+    """
+
+    def __init__(self, scale: str | None = None):
+        super().__init__()
+        self.scale = scale
+        self.register_buffer("fitted_scale", None)
+
+    @property
+    def is_trainable(self) -> bool:
+        return self.scale is None
+
+    def fit(self, train: ResidualArchive, validation: ResidualArchive | None = None) -> Self:
+        residuals = train.residuals.to(torch.float64)
+        observed = train.observed
+        if observed is None:
+            observed = torch.ones_like(train.residuals, dtype=torch.bool)
+        count = observed.sum(dim=0)
+        if (count == 0).any():
+            raise ValueError("every step and series needs an observed residual in the fit split")
+        scale = ((residuals.square() * observed).sum(dim=0) / count).sqrt()
+        if (scale == 0).any():
+            raise ValueError("a fitted scale is zero: the fit split has only zero residuals")
+        self.fitted_scale = scale.to(train.residuals.dtype)
+        return self
+
+    def _scale(self, rows: ResidualArchive) -> Tensor:
+        if self.scale is None:
+            if self.fitted_scale is None:
+                raise RuntimeError("fit() must run before a fitted scale is used")
+            return self.fitted_scale  # [H, N], broadcast over rows
+        if self.scale not in rows.outputs:
+            raise KeyError(f"the archive has no output {self.scale!r}")
+        scale = rows.outputs[self.scale]
+        if scale.shape != rows.residuals.shape:
+            raise ValueError(f"output {self.scale!r} must have shape [T, H, N]")
+        if not (scale > 0).all():
+            raise ValueError(f"output {self.scale!r} must be positive")
+        return scale
+
+    def forward(self, rows: ResidualArchive) -> Tensor:
+        return rows.residuals.abs() / self._scale(rows)
+
+    def region(self, threshold: Tensor, rows: ResidualArchive) -> Interval:
+        width = threshold * self._scale(rows)
+        return Interval(-width, width)
+
+
+__all__ = ["NormalizedScore"]

tscp/scores/signed.py

@@ -0,0 +1,46 @@
+"""Signed residuals: one score per side of the interval."""
+
+import torch
+from torch import Tensor
+
+from tscp.data import ResidualArchive
+from tscp.regions import Interval
+from tscp.registry import register
+from tscp.scores.base import Score
+
+
+@register("score", "signed")
+class SignedScore(Score):
+    """Two one-sided scores per element, for intervals that need not be symmetric.
+
+    Channel ``lower`` scores ``-r`` and channel ``upper`` scores ``r``; thresholds
+    ``q_lower`` and ``q_upper`` give the interval ``[-q_lower, q_upper]``. The
+    miscoverage is shared between the sides, ``lower_share * alpha`` below and the rest
+    above, so by a union bound the interval misses with probability at most ``alpha``.
+    Skewed errors get a narrower side where they are rare.
+
+    Args:
+        lower_share: Fraction of ``alpha`` spent on the lower side, in (0, 1).
+    """
+
+    channels = ("lower", "upper")
+
+    def __init__(self, lower_share: float = 0.5):
+        super().__init__()
+        if not 0 < lower_share < 1:
+            raise ValueError("lower_share must lie in (0, 1)")
+        self.lower_share = float(lower_share)
+
+    def forward(self, rows: ResidualArchive) -> Tensor:
+        residuals = rows.residuals
+        return torch.stack([-residuals, residuals], dim=-1)
+
+    def region(self, threshold: Tensor, rows: ResidualArchive) -> Interval:
+        return Interval(-threshold[..., 0], threshold[..., 1])
+
+    def levels(self, alpha: float, kept: tuple[int, ...]) -> Tensor:
+        shares = torch.tensor([self.lower_share, 1 - self.lower_share], dtype=torch.float64)
+        return (float(alpha) * shares).expand(kept).clone()
+
+
+__all__ = ["SignedScore"]

tscp/sources/__init__.py

@@ -0,0 +1,7 @@
+"""Axis 1, residual source: which past errors calibrate."""
+
+from .base import Source, calibration_rows
+from .expanding import ExpandingSource
+from .holdout import HoldoutSource
+
+__all__ = ["ExpandingSource", "HoldoutSource", "Source", "calibration_rows"]

tscp/sources/base.py

@@ -0,0 +1,32 @@
+"""The residual-source interface (axis 1)."""
+
+from torch import Tensor
+
+from tscp.data import ResidualArchive
+from tscp.utils import Component
+
+
+class Source(Component):
+    """Which past residuals calibrate.
+
+    :meth:`rows` names the archive rows scored at calibration time. An expanding source
+    also adds each test residual to the pool once its target time has passed (see
+    :mod:`tscp.data.availability`); a static source keeps the pool fixed.
+    """
+
+    #: Whether test residuals join the pool once they are known.
+    expanding: bool = False
+
+    def rows(self, archive: ResidualArchive) -> Tensor:
+        """Return the archive rows scored at calibration time."""
+        raise NotImplementedError
+
+
+def calibration_rows(archive: ResidualArchive) -> Tensor:
+    """Return the rows of the calibration split, with a clear error if there is none."""
+    if archive.splits is None or "calibration" not in archive.splits:
+        raise ValueError("this source needs an archive with a 'calibration' split")
+    return archive.splits["calibration"]
+
+
+__all__ = ["Source", "calibration_rows"]

tscp/sources/expanding.py

@@ -0,0 +1,25 @@
+"""The calibration split plus test residuals as they become known."""
+
+from torch import Tensor
+
+from tscp.data import ResidualArchive
+from tscp.registry import register
+from tscp.sources.base import Source, calibration_rows
+
+
+@register("source", "expanding")
+class ExpandingSource(Source):
+    """The calibration split, plus each test residual once its target time has passed.
+
+    The pool at test origin ``t`` holds every calibration residual and every test
+    residual of (origin ``s``, step ``h``) with ``s + h <= t``. The ``fit`` split never
+    joins the pool: components were fitted on it.
+    """
+
+    expanding = True
+
+    def rows(self, archive: ResidualArchive) -> Tensor:
+        return calibration_rows(archive)
+
+
+__all__ = ["ExpandingSource"]

tscp/sources/holdout.py

@@ -0,0 +1,18 @@
+"""The calibration split as a fixed pool."""
+
+from torch import Tensor
+
+from tscp.data import ResidualArchive
+from tscp.registry import register
+from tscp.sources.base import Source, calibration_rows
+
+
+@register("source", "holdout")
+class HoldoutSource(Source):
+    """The calibration split, fixed for the whole test period (split conformal)."""
+
+    def rows(self, archive: ResidualArchive) -> Tensor:
+        return calibration_rows(archive)
+
+
+__all__ = ["HoldoutSource"]

tscp/testing/__init__.py

@@ -0,0 +1,40 @@
+"""Checks and fixtures for anyone who builds on tscp's interfaces.
+
+The checks verify that a method or component keeps tscp's contracts: causality, split
+discipline, config round trips, devices, and each axis's own rules. tscp checks its own
+presets and components with them; a method or component written elsewhere can be checked
+the same way, in any test framework::
+
+    from tscp.testing import check_score
+
+    check_score(lambda: MyScore(width=2.0))
+"""
+
+from .archives import HOUR, MONDAY, synthetic_archive, with_missing_targets
+from .checks import (
+    assert_regions_equal,
+    check_feature_map,
+    check_method,
+    check_online_update,
+    check_quantile_model,
+    check_region,
+    check_score,
+    check_weights,
+)
+from .components import MaxAbsScore
+
+__all__ = [
+    "HOUR",
+    "MONDAY",
+    "MaxAbsScore",
+    "assert_regions_equal",
+    "check_feature_map",
+    "check_method",
+    "check_online_update",
+    "check_quantile_model",
+    "check_region",
+    "check_score",
+    "check_weights",
+    "synthetic_archive",
+    "with_missing_targets",
+]

tscp/testing/archives.py

@@ -0,0 +1,80 @@
+"""Small synthetic archives for checks and tests."""
+
+from dataclasses import replace
+
+import torch
+
+from tscp.data import ResidualArchive
+from tscp.datasets import variance_shift
+
+MONDAY = 1_767_571_200_000_000_000
+"""2026-01-05 00:00 UTC, a Monday, in nanoseconds: the first origin of synthetic archives."""
+HOUR = 3_600_000_000_000
+"""One hour in nanoseconds: the base step of synthetic archives."""
+
+
+def with_missing_targets(
+    archive: ResidualArchive, fraction: float, seed: int = 0
+) -> ResidualArchive:
+    """Return ``archive`` with a random ``fraction`` of its targets marked unobserved.
+
+    Unobserved residuals become exactly 0, as the archive requires. Targets that were
+    already unobserved stay so.
+    """
+    if not 0 <= fraction < 1:
+        raise ValueError("fraction must lie in [0, 1)")
+    generator = torch.Generator().manual_seed(seed)
+    observed = (torch.rand(archive.residuals.shape, generator=generator) >= fraction).to(
+        archive.device
+    )
+    if archive.observed is not None:
+        observed = observed & archive.observed
+    return replace(archive, residuals=archive.residuals * observed, observed=observed)
+
+
+def synthetic_archive(
+    *,
+    horizon: int = 2,
+    num_series: int = 1,
+    num_origins: int = 300,
+    missing: float = 0.0,
+    seed: int = 0,
+) -> ResidualArchive:
+    """A small archive whose error scale jumps during the test split, with forecaster outputs.
+
+    The residuals come from :func:`~tscp.datasets.variance_shift`, with its default splits.
+    The archive also holds what tscp's own components read: the outputs ``scale``
+    (positive) and a band ``lower`` and ``upper`` one unit around the forecasts; two
+    random context columns, ``load`` and ``temperature``; and timestamps, one hour apart
+    from :data:`MONDAY`. Every built-in score and feature map can run on it, and with
+    ``missing > 0`` so can the code paths for unobserved targets.
+
+    Args:
+        horizon: Number of steps ``H``.
+        num_series: Number of series ``N``.
+        num_origins: Number of forecast origins ``T``.
+        missing: Fraction of targets to mark unobserved.
+        seed: Seed of every random draw.
+    """
+    archive = variance_shift(
+        horizon=horizon, num_origins=num_origins, num_series=num_series, seed=seed
+    )
+    generator = torch.Generator().manual_seed(seed + 1)
+    outputs = {
+        "scale": 0.5 + torch.rand(archive.residuals.shape, generator=generator),
+        "lower": archive.forecasts - 1.0,
+        "upper": archive.forecasts + 1.0,
+    }
+    archive = replace(
+        archive,
+        outputs=outputs,
+        context=torch.randn(num_origins, 2, generator=generator),
+        context_names=("load", "temperature"),
+        timestamps=MONDAY + HOUR * archive.origins,
+    )
+    if missing:
+        archive = with_missing_targets(archive, missing, seed=seed + 2)
+    return archive
+
+
+__all__ = ["HOUR", "MONDAY", "synthetic_archive", "with_missing_targets"]