conforme 0.1.0__py3-none-any.whl

conforme/__init__.py

@@ -0,0 +1,81 @@
+"""Conforme: point forecasts, hierarchy reconciliation, conformal bounds, and orders.
+
+Vendor model adapters live in `conforme.forecast.models` and need their extra installed.
+"""
+
+from conforme.backtest import Forecasts, Replay, replay, rolling_forecasts
+from conforme.conformal import (
+    ACI,
+    Absolute,
+    Calibrator,
+    Feedback,
+    LeadTime,
+    Level,
+    Loss,
+    Miss,
+    QuantileCalibrator,
+    QuantileTracker,
+    RiskControl,
+    Score,
+    Signed,
+    SplitQuantile,
+    State,
+    Step,
+    Target,
+)
+from conforme.data import Hierarchy, Panel
+from conforme.decision import Settlement, critical_ratio, order_up_to, settle
+from conforme.forecast import (
+    BottomUp,
+    Covariate,
+    Fitted,
+    Forecaster,
+    Identity,
+    Reconciler,
+    SeasonalNaive,
+    Window,
+    WlsStruct,
+)
+from conforme.online import Issue, initial_state, step
+
+__all__ = [
+    "ACI",
+    "Absolute",
+    "BottomUp",
+    "Calibrator",
+    "Covariate",
+    "Feedback",
+    "Fitted",
+    "Forecaster",
+    "Forecasts",
+    "Hierarchy",
+    "Identity",
+    "Issue",
+    "LeadTime",
+    "Level",
+    "Loss",
+    "Miss",
+    "QuantileCalibrator",
+    "Panel",
+    "QuantileTracker",
+    "RiskControl",
+    "Reconciler",
+    "Replay",
+    "Score",
+    "SeasonalNaive",
+    "Settlement",
+    "Signed",
+    "SplitQuantile",
+    "State",
+    "Step",
+    "Target",
+    "Window",
+    "WlsStruct",
+    "critical_ratio",
+    "initial_state",
+    "order_up_to",
+    "replay",
+    "rolling_forecasts",
+    "settle",
+    "step",
+]

conforme/backtest/__init__.py

@@ -0,0 +1,6 @@
+"""Backtests: rolling-origin forecasts, and online calibration replayed over them."""
+
+from conforme.backtest.forecasts import Forecasts, rolling_forecasts
+from conforme.backtest.replay import Replay, replay
+
+__all__ = ["Forecasts", "Replay", "replay", "rolling_forecasts"]

conforme/backtest/forecasts.py

@@ -0,0 +1,142 @@
+"""Rolling-origin point forecasts: fit, predict, and reconcile at each origin.
+
+`rolling_forecasts` keeps no state between calls and stores nothing. Each window is a
+read-only slice that ends at its origin, so a model sees only what was known there.
+"""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+
+from conforme.data.hierarchy import Hierarchy
+from conforme.data.panel import Panel
+from conforme.forecast.models.base import Covariate, Fitted, Forecaster, Window
+from conforme.forecast.reconcile import Reconciler
+
+
+@dataclass(frozen=True)
+class Forecasts:
+    """Reconciled points `[O, N, H]` for increasing origins `[O]`."""
+
+    origins: np.ndarray
+    points: np.ndarray
+
+    def residuals(self, actuals: np.ndarray) -> np.ndarray:
+        """Return `actual - point` `[O, N, H]` from node actuals `[N, T]`.
+
+        A target after the last period is NaN, which means not yet known.
+        """
+        n_periods = actuals.shape[1]
+        targets = self.origins[:, None] + np.arange(1, self.points.shape[2] + 1)
+        values = actuals[:, np.minimum(targets, n_periods - 1)].transpose(1, 0, 2)
+        resid = values.astype(np.float32) - self.points
+        return np.where((targets < n_periods)[:, None, :], resid, np.float32(np.nan))
+
+
+def rolling_forecasts(
+    panel: Panel,
+    hierarchy: Hierarchy,
+    model: Forecaster,
+    reconciler: Reconciler,
+    origins: np.ndarray,
+    horizon: int,
+    refit_every: int | None = None,
+    covariates: Mapping[str, Covariate] | None = None,
+) -> Forecasts:
+    """Fit, predict, and reconcile at each origin, the index of the last observed period.
+
+    The model forecasts the first S nodes, with S from the reconciler shape `(N, S)`. It
+    is fitted at the first origin and again every `refit_every` origins. None fits once.
+    """
+    origins = _check_schedule(origins, len(panel.periods), horizon, refit_every)
+    covariates = dict(covariates or {})
+    n_nodes, n_series = reconciler.shape
+    if n_nodes != len(hierarchy.nodes) or n_series not in (hierarchy.n_bottom, n_nodes):
+        raise ValueError(f"reconciler shape {reconciler.shape} does not fit the hierarchy")
+    last = int(origins[-1])
+    for name, covariate in covariates.items():
+        _check_covariate(name, covariate, hierarchy.n_bottom, last, horizon)
+
+    history = _series_rows(panel.values, hierarchy, n_series, "sum")
+    inputs = {
+        name: _series_rows(covariate.values, hierarchy, n_series, covariate.aggregate)
+        for name, covariate in covariates.items()
+    }
+    reach = {name: _reach(covariate, horizon) for name, covariate in covariates.items()}
+    periods = pd.date_range(panel.periods[0], periods=last + 1 + horizon, freq=panel.freq)
+
+    points = np.empty((len(origins), n_nodes, horizon), dtype=np.float32)
+    fitted: Fitted | None = None
+    for index, origin in enumerate(origins):
+        seen = int(origin) + 1
+        window = Window(
+            y=history[:, :seen],
+            x={name: _visible(values, seen, reach[name]) for name, values in inputs.items()},
+            periods=periods[: seen + horizon],
+            horizon=horizon,
+        )
+        if fitted is None or (refit_every is not None and index % refit_every == 0):
+            fitted = model.fit(window)
+        base = np.asarray(fitted.predict(window))
+        if base.shape != (n_series, horizon):
+            raise ValueError(f"model returned shape {base.shape}, expected {(n_series, horizon)}")
+        if not np.isfinite(base).all():
+            raise ValueError(f"model returned nonfinite points at origin {origin}")
+        points[index] = reconciler(base)
+    return Forecasts(origins=origins, points=points)
+
+
+def _check_schedule(
+    origins: np.ndarray, n_periods: int, horizon: int, refit_every: int | None
+) -> np.ndarray:
+    origins = np.asarray(origins)
+    if origins.ndim != 1 or len(origins) == 0 or not np.issubdtype(origins.dtype, np.integer):
+        raise ValueError("origins must be a non-empty vector of period indexes")
+    if (np.diff(origins) <= 0).any():
+        raise ValueError("origins must be strictly increasing")
+    if origins[0] < 0 or origins[-1] >= n_periods:
+        raise ValueError(f"origins must be in [0, {n_periods - 1}]")
+    if horizon < 1:
+        raise ValueError(f"horizon must be at least 1, got {horizon}")
+    if refit_every is not None and refit_every < 1:
+        raise ValueError(f"refit_every must be at least 1, got {refit_every}")
+    return origins.astype(np.int64)
+
+
+def _check_covariate(
+    name: str, covariate: Covariate, n_bottom: int, last: int, horizon: int
+) -> None:
+    rows, length = covariate.values.shape
+    if rows not in (1, n_bottom):
+        raise ValueError(f"covariate {name!r} must have one row or one row per bottom series")
+    needed = last + 1 + (horizon if covariate.known_ahead else 0)
+    if length != 1 and length < needed:
+        raise ValueError(f"covariate {name!r} has {length} periods, needs {needed}")
+
+
+def _series_rows(
+    values: np.ndarray, hierarchy: Hierarchy, n_series: int, aggregate: str
+) -> np.ndarray:
+    """Read-only rows for the first `n_series` nodes. A single row is shared by all."""
+    if len(values) > 1 and n_series > hierarchy.n_bottom:
+        nodes = hierarchy.summing[:n_series]
+        values = nodes @ values
+        if aggregate == "mean":
+            values = values / nodes.sum(axis=1)[:, None]
+        values = values.astype(np.float32)
+    view = values.view()
+    view.flags.writeable = False
+    return view
+
+
+def _reach(covariate: Covariate, horizon: int) -> int | None:
+    """Periods visible after the origin. None for a static covariate."""
+    if covariate.values.shape[1] == 1:
+        return None
+    return horizon if covariate.known_ahead else 0
+
+
+def _visible(values: np.ndarray, seen: int, reach: int | None) -> np.ndarray:
+    return values if reach is None else values[:, : seen + reach]

conforme/backtest/replay.py

@@ -0,0 +1,96 @@
+"""Replay: online calibration over the origins of a backtest, kept for assessment."""
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from conforme.backtest.forecasts import Forecasts
+from conforme.conformal.calibrators.base import Calibrator, State
+from conforme.conformal.scores import Score
+from conforme.conformal.targets import Target, columns
+from conforme.online.step import initial_state, step
+
+
+@dataclass(frozen=True)
+class Replay:
+    """Calibration over origins `[O]`. Arrays are `[O, N, C]`.
+
+    `target` and `score` are NaN when the target is not known at the end of the data.
+    `state` continues the run with `conforme.online.step`.
+    """
+
+    origins: np.ndarray
+    point: np.ndarray
+    threshold: np.ndarray
+    lower: np.ndarray
+    upper: np.ndarray
+    target: np.ndarray
+    score: np.ndarray
+    censored: np.ndarray
+    state: State
+
+    @property
+    def covered(self) -> np.ndarray:
+        """1.0 when the score is within its threshold, NaN when not known."""
+        known = np.isfinite(self.score)
+        return np.where(known, (self.score <= self.threshold).astype(np.float32), np.nan)
+
+
+def replay(
+    forecasts: Forecasts,
+    actuals: np.ndarray,
+    *,
+    target: Target,
+    score: Score,
+    calibrator: Calibrator,
+    censored: np.ndarray | None = None,
+) -> Replay:
+    """Run `conforme.online.step` at each origin of `forecasts` on node actuals `[N, T]`."""
+    origins = forecasts.origins
+    n_origins, n_nodes, horizon = forecasts.points.shape
+    if censored is None:
+        censored = np.zeros(actuals.shape, dtype=bool)
+    state = initial_state(target, calibrator, n_nodes, horizon)
+    issued = []
+    previous = -1
+    for index, origin in enumerate(origins):
+        seen = slice(previous + 1, int(origin) + 1)
+        state, out = step(
+            state,
+            int(origin),
+            forecasts.points[index],
+            actuals[:, seen],
+            target=target,
+            score=score,
+            calibrator=calibrator,
+            censored=censored[:, seen],
+        )
+        issued.append(out)
+        previous = int(origin)
+    cover = target.cover(horizon)
+    targets, target_censored = _targets(actuals, censored, origins, horizon, cover)
+    point = np.stack([out.point for out in issued])
+    return Replay(
+        origins=origins,
+        point=point,
+        threshold=np.stack([out.threshold for out in issued]),
+        lower=np.stack([out.lower for out in issued]),
+        upper=np.stack([out.upper for out in issued]),
+        target=targets,
+        score=score.score(targets, point),
+        censored=target_censored,
+        state=state,
+    )
+
+
+def _targets(
+    actuals: np.ndarray, censored: np.ndarray, origins: np.ndarray, horizon: int, cover: np.ndarray
+) -> tuple[np.ndarray, np.ndarray]:
+    """Targets and censoring per column `[O, N, C]`, NaN after the last period."""
+    n_periods = actuals.shape[1]
+    steps = origins[:, None] + np.arange(1, horizon + 1)
+    known = steps < n_periods
+    clipped = np.minimum(steps, n_periods - 1)
+    values = np.where(known[:, None, :], actuals[:, clipped].transpose(1, 0, 2), np.nan)
+    flags = censored[:, clipped].transpose(1, 0, 2) & known[:, None, :]
+    return columns(values.astype(np.float32), cover), columns(flags, cover)

conforme/conformal/__init__.py

@@ -0,0 +1,42 @@
+"""Conformal calibration: targets, scores, and calibration methods. No time, no origins.
+
+A `Target` says which quantity each column bounds, a `Score` which bound each threshold
+issues, a `Loss` what a bound cost, and a `Calibrator` turns the known targets into a
+threshold per node and column.
+`conforme.online` runs them origin by origin.
+"""
+
+from conforme.conformal.calibrators import (
+    ACI,
+    Calibrator,
+    Feedback,
+    Level,
+    QuantileCalibrator,
+    QuantileTracker,
+    RiskControl,
+    SplitQuantile,
+    State,
+)
+from conforme.conformal.losses import Loss, Miss
+from conforme.conformal.scores import Absolute, Score, Signed
+from conforme.conformal.targets import LeadTime, Step, Target
+
+__all__ = [
+    "ACI",
+    "Absolute",
+    "Calibrator",
+    "Feedback",
+    "LeadTime",
+    "Level",
+    "Loss",
+    "Miss",
+    "QuantileCalibrator",
+    "QuantileTracker",
+    "RiskControl",
+    "Score",
+    "Signed",
+    "SplitQuantile",
+    "State",
+    "Step",
+    "Target",
+]

conforme/conformal/calibrators/__init__.py

@@ -0,0 +1,25 @@
+"""Calibration methods. A method is one module that implements `base.Calibrator`."""
+
+from conforme.conformal.calibrators.aci import ACI
+from conforme.conformal.calibrators.base import (
+    Calibrator,
+    Feedback,
+    Level,
+    QuantileCalibrator,
+    State,
+)
+from conforme.conformal.calibrators.risk import RiskControl
+from conforme.conformal.calibrators.split import SplitQuantile
+from conforme.conformal.calibrators.tracker import QuantileTracker
+
+__all__ = [
+    "ACI",
+    "Calibrator",
+    "Feedback",
+    "Level",
+    "QuantileCalibrator",
+    "QuantileTracker",
+    "RiskControl",
+    "SplitQuantile",
+    "State",
+]

conforme/conformal/calibrators/aci.py

@@ -0,0 +1,42 @@
+"""Adaptive conformal inference: a working level that reacts to misses."""
+
+import numpy as np
+
+from conforme.conformal.calibrators.base import Calibrator, Feedback, QuantileCalibrator, State
+
+
+class ACI(Calibrator):
+    """Adaptive conformal inference (Gibbs and Candès 2021), per node and column.
+
+    After each known score, the working level moves by `gamma * (miss - (1 - level))`,
+    where a miss is a score above the threshold that was issued for it. The base
+    calibrator gives the threshold at the working level. The target level is the level
+    of the base. A working level at or above one gives an infinite threshold, at or
+    below zero an empty interval.
+    """
+
+    def __init__(self, base: QuantileCalibrator, gamma: float = 0.005) -> None:
+        if gamma <= 0:
+            raise ValueError(f"gamma must be positive, got {gamma}")
+        self.base = base
+        self.level = base.level
+        self.gamma = gamma
+
+    def initial_state(self, n_nodes: int, n_columns: int) -> State:
+        return {
+            "base": self.base.initial_state(n_nodes, n_columns),
+            "level": np.full((n_nodes, n_columns), np.nan),
+        }
+
+    def update(self, state: State, feedback: Feedback) -> State:
+        working = np.where(np.isnan(state["level"]), self.level, state["level"])
+        misses, known = feedback.misses(working.shape[1])
+        working = working + self.gamma * (misses - (1 - self.level) * known)
+        return {"base": self.base.update(state["base"], feedback), "level": working}
+
+    def threshold(self, state: State) -> np.ndarray:
+        working = np.where(np.isnan(state["level"]), self.level, state["level"])
+        inside = np.clip(working, 1e-6, 1 - 1e-6)
+        out = self.base.threshold_at(state["base"], inside)
+        out = np.where(working >= 1, np.inf, out)
+        return np.where(working <= 0, -np.inf, out).astype(np.float32)

conforme/conformal/calibrators/base.py

@@ -0,0 +1,97 @@
+"""The calibrator contract: what a calibration method receives, keeps, and returns.
+
+A calibrator turns the targets known so far into a threshold per node and column. A
+threshold indexes a nested family of bounds, the `Score`: a quantile calibrator ranks
+the scores, and a risk calibrator picks the smallest threshold whose bounds have a low
+enough loss. Its
+state is a nested dict of numpy arrays, and its methods are functions of that state.
+So a product can save the state after each origin and continue later, and a backtest
+is the same loop as production. A call owns the state it receives: it can write into
+those arrays, and the caller continues only with the returned state.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+
+from conforme.conformal.scores import Score
+
+State = dict[str, Any]
+"""Nested dict of numpy arrays. `conforme.online.state` flattens it for storage."""
+
+Level = float | np.ndarray
+"""Target level: a scalar, or `[N, C]` per node and column. `[N, 1]` is one per node."""
+
+
+@dataclass(frozen=True)
+class Feedback:
+    """Targets that became known at one origin. Each row `[K]` is one target column of
+    one issuing origin, for all nodes.
+
+    Rows are in origin order. `point` and `target` are the column sums `[K, N]`, NaN
+    where the actual is missing. `issued` is the threshold that was issued for each
+    row, `censored` marks targets that are lower bounds, and `score` is the family of
+    bounds the thresholds index, so a calibrator can find the bounds of any threshold.
+    """
+
+    origin: np.ndarray
+    column: np.ndarray
+    point: np.ndarray
+    target: np.ndarray
+    issued: np.ndarray
+    censored: np.ndarray
+    score: Score
+
+    @property
+    def scores(self) -> np.ndarray:
+        """Nonconformity scores `[K, N]` float32: the smallest threshold that holds the target."""
+        return self.score.score(self.target, self.point).astype(np.float32)
+
+    def misses(self, n_columns: int) -> tuple[np.ndarray, np.ndarray]:
+        """Counts `[N, C]` of misses (score above the issued threshold) and known scores."""
+        scores = self.scores
+        known = np.isfinite(scores)
+        miss = (scores > self.issued) & known
+        columns = np.eye(n_columns)[self.column]  # [K, C]
+        return miss.T @ columns, known.T @ columns
+
+
+class Calibrator(ABC):
+    """A calibration method. It owns its target level, set at construction."""
+
+    @abstractmethod
+    def initial_state(self, n_nodes: int, n_columns: int) -> State:
+        """Return the empty state."""
+
+    @abstractmethod
+    def update(self, state: State, feedback: Feedback) -> State:
+        """Return the state after the feedback. It can reuse the input arrays."""
+
+    @abstractmethod
+    def threshold(self, state: State) -> np.ndarray:
+        """Return thresholds `[N, C]` at the target level. inf means not ready."""
+
+
+class QuantileCalibrator(Calibrator):
+    """A calibrator that can give its threshold at any level, not only its own.
+
+    Wrappers such as `ACI` move the level and ask the base for the threshold there.
+    """
+
+    level: Level
+
+    @abstractmethod
+    def threshold_at(self, state: State, level: Level) -> np.ndarray:
+        """Return thresholds `[N, C]` at `level` instead of the target level."""
+
+
+def check_level(level: Level) -> Level:
+    """A scalar or `[N, C]` level strictly between zero and one."""
+    values = np.asarray(level, dtype=np.float64)
+    if values.ndim not in (0, 2):
+        raise ValueError(f"level must be a scalar or [N, C], got shape {values.shape}")
+    if not np.isfinite(values).all() or ((values <= 0) | (values >= 1)).any():
+        raise ValueError("level must be strictly between zero and one")
+    return float(values) if values.ndim == 0 else values

conforme/conformal/calibrators/ranks.py

@@ -0,0 +1,92 @@
+"""Finite-sample score quantiles, with rolling retention and pooling.
+
+These functions hold the rank rules of the library. Calibrators call them on the
+scores they keep.
+"""
+
+import numpy as np
+
+
+def score_quantile(scores: np.ndarray, level: float | np.ndarray) -> np.ndarray:
+    """Finite-sample quantile of finite scores along axis 0, without interpolation.
+
+    A vector is one pool; a matrix is independent pools in columns. `level` is a
+    scalar or one value per output. The rank is ceil((n + 1) * level); insufficient
+    samples give inf.
+    """
+    scores = np.asarray(scores)
+    level = np.asarray(level)
+    if scores.ndim not in (1, 2) or level.ndim > 1:
+        raise ValueError("scores must be a vector or matrix and level a scalar or vector")
+    if not np.isfinite(level).all() or ((level <= 0) | (level >= 1)).any():
+        raise ValueError("level must be strictly between zero and one")
+    if not np.isfinite(scores).all():
+        raise ValueError("scores must be finite; select only resolved observations")
+    shape = scores.shape[1:] if scores.ndim == 2 else np.shape(level)
+    ranks = np.ceil((len(scores) + 1) * np.broadcast_to(level, shape)).astype(np.int64)
+    out = np.full(shape, np.inf, dtype=np.result_type(scores.dtype, np.float32))
+    ready = ranks <= len(scores)
+    if ready.any():
+        ordered = np.sort(scores, axis=0)
+        if scores.ndim == 1:
+            out[ready] = ordered[ranks[ready] - 1]
+        else:
+            columns = np.nonzero(ready)[0]
+            out[ready] = ordered[ranks[ready] - 1, columns]
+    return out
+
+
+def retained_quantile(
+    scores: np.ndarray,
+    level: float | np.ndarray,
+    window: int | None = None,
+    groups: np.ndarray | None = None,
+) -> np.ndarray:
+    """Quantile per node `[N]` from scores `[K, N]` in origin order. NaN is no score.
+
+    `window` keeps the last K resolved rows per pool, before pooling. A row is resolved
+    for a pool when it has at least one finite score there, so holes do not consume
+    rows. `groups` has one integer per node: equal labels pool their scores, and every
+    member gets the pool quantile. `level` is a scalar or one value per node.
+    """
+    if window is not None:
+        if window < 1:
+            raise ValueError(f"window must be at least 1, got {window}")
+        # Fast path: when the last K rows are complete, they are the retained rows.
+        if np.isfinite(scores[-window:]).all():
+            scores = scores[-window:]
+    if groups is None:
+        if window is not None and len(scores) > window:
+            finite = np.isfinite(scores)
+            retained = np.cumsum(finite[::-1], axis=0)[::-1] <= window
+            scores = np.where(finite & retained, scores, np.nan)
+            scores = scores[np.isfinite(scores).any(axis=1)]
+        return _finite_quantile(scores, level)
+    levels = np.broadcast_to(level, (scores.shape[1],))
+    out = np.full(scores.shape[1], np.inf, dtype=np.float32)
+    order = np.argsort(groups)
+    labels = groups[order]
+    for columns in np.split(order, np.flatnonzero(labels[1:] != labels[:-1]) + 1):
+        pool = scores[:, columns]
+        pool = pool[np.isfinite(pool).any(axis=1)]
+        if window is not None:
+            pool = pool[-window:]
+        out[columns] = score_quantile(pool[np.isfinite(pool)], levels[columns])
+    return out
+
+
+def _finite_quantile(scores: np.ndarray, level: float | np.ndarray) -> np.ndarray:
+    """Independent column ranks from finite counts; NaN cells supply no score."""
+    if np.isfinite(scores).all():
+        return score_quantile(scores, level).astype(np.float32)
+    counts = np.isfinite(scores).sum(axis=0)
+    levels = np.broadcast_to(level, counts.shape)
+    # Match score_quantile's level dtype arithmetic, including float32 levels.
+    ranks = np.ceil((counts + 1).astype(levels.dtype) * levels).astype(np.int64)
+    out = np.full(counts.shape, np.inf, dtype=np.float32)
+    ready = (ranks <= counts) & (counts > 0)
+    if ready.any():
+        ordered = np.sort(np.where(np.isfinite(scores), scores, np.nan), axis=0)
+        columns = np.flatnonzero(ready)
+        out[columns] = ordered[ranks[columns] - 1, columns]
+    return out