choircert 0.1.0__py3-none-any.whl

choir/__init__.py

@@ -0,0 +1,38 @@
+"""choir: a certification layer for ordinal, safety-critical prediction.
+
+Guarantees are statements about prediction-set coverage and expected risk under
+declared sampling assumptions. No causal quantities are estimated or reported.
+"""
+
+from choir.core.scores import cumulative_score, score_matrix, cdf_from_proba
+from choir.core.intervals import interval_sets, expand_intervals
+from choir.core.calibrate import (
+    conformal_quantile,
+    split_calibrate,
+    mondrian_calibrate,
+    weighted_quantile,
+)
+from choir.noise import NoiseModel
+from choir.partitions import Partition
+from choir.compose import Certificate, CertifiedOrdinal
+from choir.risk import crc_threshold, inflated_costs
+
+__all__ = [
+    "cumulative_score",
+    "score_matrix",
+    "cdf_from_proba",
+    "interval_sets",
+    "expand_intervals",
+    "conformal_quantile",
+    "split_calibrate",
+    "mondrian_calibrate",
+    "weighted_quantile",
+    "NoiseModel",
+    "Partition",
+    "Certificate",
+    "CertifiedOrdinal",
+    "crc_threshold",
+    "inflated_costs",
+]
+
+__version__ = "0.1.0"

choir/compose.py

@@ -0,0 +1,196 @@
+"""Certificate objects, slack-budget algebra, and the CertifiedOrdinal API
+(methods.tex Thm 6; CHOIR_framework.md 5.1).
+
+Canonical composition order, enforced by construction:
+condition (partition) -> weight (within cell) -> calibrate -> expand (noise) -> risk-adjust.
+Slacks are additive and each is attributed to one declared assumption (Thm 6).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+
+from choir.core.scores import cdf_from_proba, cumulative_score
+from choir.core.intervals import interval_sets
+from choir.core.calibrate import conformal_quantile
+from choir.noise import NoiseModel
+from choir.partitions import Partition
+from choir.risk import crc_threshold, inflated_costs
+
+
+@dataclass(frozen=True)
+class Certificate:
+    """A coverage certificate: nominal level minus named, attributed slacks."""
+
+    nominal: float                      # 1 - alpha
+    slacks: dict = field(default_factory=dict)  # name -> (value, assumption)
+    cell: object = None
+    n_cal: int = 0
+
+    @property
+    def floor(self) -> float:
+        return self.nominal - sum(v for v, _ in self.slacks.values())
+
+    def as_row(self) -> dict:
+        row = {"cell": self.cell, "n_cal": self.n_cal, "nominal": self.nominal,
+               "floor": self.floor}
+        for name, (v, assumption) in self.slacks.items():
+            row[f"slack_{name}"] = v
+            row[f"assumption_{name}"] = assumption
+        return row
+
+
+class CertifiedOrdinal:
+    """Wrap any ordinal severity model; export certified interval predictions.
+
+    base: object with predict_proba(X) -> (n, K), or a callable X -> conditional CDF
+    (n, K). The base model must be fit on the training split only.
+    partition: None | Partition | anything Partition accepts (fit on training split).
+    noise: NoiseModel or None.
+    n_min: per-cell floor; cells below it roll up (product cell -> class -> global).
+    """
+
+    def __init__(self, base, K: int = 5, partition=None, noise: NoiseModel | None = None,
+                 n_min: int = 1000):
+        self.base = base
+        self.K = K
+        self.partition = (partition if isinstance(partition, Partition) or partition is None
+                          else Partition(partition))
+        self.noise = noise
+        self.n_min = n_min
+        self._cal: dict | None = None
+
+    # -- base-model plumbing --
+
+    def _cdf(self, X) -> np.ndarray:
+        if callable(self.base) and not hasattr(self.base, "predict_proba"):
+            cdf = np.asarray(self.base(X), dtype=float)
+        else:
+            cdf = cdf_from_proba(self.base.predict_proba(X))
+        if cdf.shape[1] != self.K:
+            raise ValueError(f"base model emits {cdf.shape[1]} categories, expected {self.K}")
+        return cdf
+
+    def fit(self, X_train, y_train):
+        if hasattr(self.base, "fit"):
+            self.base.fit(X_train, np.asarray(y_train))
+        return self
+
+    # -- calibration (condition -> calibrate) --
+
+    def _keys(self, X, strata=None) -> tuple[np.ndarray, np.ndarray]:
+        """Return (cell_keys, class_keys) as string arrays 'class|stratum'."""
+        cls = self.partition.labels(X) if self.partition is not None else np.zeros(len(X), int)
+        cls_keys = np.array([str(c) for c in cls])
+        if strata is None:
+            return cls_keys.copy(), cls_keys
+        strata = np.asarray(strata)
+        cell_keys = np.array([f"{c}|{g}" for c, g in zip(cls_keys, strata)])
+        return cell_keys, cls_keys
+
+    def calibrate(self, X_cal, y_cal, strata=None):
+        y_cal = np.asarray(y_cal)
+        scores = cumulative_score(self._cdf(X_cal), y_cal)
+        cell_keys, cls_keys = self._keys(X_cal, strata)
+        self._cal = {
+            "scores": scores, "y": y_cal,
+            "cell_keys": cell_keys, "class_keys": cls_keys,
+        }
+        return self
+
+    def _threshold_for(self, key: str, cls_key: str, alpha: float) -> tuple[float, int, str]:
+        """Rollup: product cell -> class -> global, first level with n >= n_min."""
+        cal = self._cal
+        for level, mask in (
+            ("cell", cal["cell_keys"] == key),
+            ("class", cal["class_keys"] == cls_key),
+            ("global", np.ones(len(cal["scores"]), bool)),
+        ):
+            n = int(mask.sum())
+            if n >= self.n_min or level == "global":
+                return conformal_quantile(cal["scores"][mask], alpha), n, level
+        raise AssertionError("unreachable")
+
+    # -- prediction (calibrate -> expand) --
+
+    def predict_set(self, X, alpha: float = 0.1, strata=None):
+        """Contiguous KABCO intervals with per-cell thresholds and noise expansion.
+
+        Returns (lo, hi), 1-indexed inclusive endpoints on the TRUE-label scale if a
+        noise model is set (expanded), else on the reported-label scale.
+        """
+        if self._cal is None:
+            raise RuntimeError("call calibrate() first")
+        cdf = self._cdf(X)
+        keys, cls_keys = self._keys(X, strata)
+        uniq, inverse = np.unique(keys, return_inverse=True)
+        thr = np.empty(len(uniq))
+        for j, key in enumerate(uniq):
+            cls_key = cls_keys[np.argmax(inverse == j)]
+            thr[j], _, _ = self._threshold_for(key, cls_key, alpha)
+        lam = thr[inverse]
+        lo, hi = interval_sets(cdf, lam)
+        if self.noise is not None:
+            lo, hi = self.noise.expand(lo, hi)
+        return lo, hi
+
+    def predict_set_risk(self, X, beta: float = 0.05, kappa=None, strata=None):
+        """Severity-cost risk-controlled sets (Thm 5a/5b), cell-wise CRC thresholds.
+
+        With a noise model set, CRC runs on band-inflated costs kappa_plus and the
+        output is expanded (Thm 5b guarantee: risk <= beta*kmax + delta*kmax).
+        """
+        if self._cal is None:
+            raise RuntimeError("call calibrate() first")
+        if kappa is None:
+            from choir.crash.costs import usdot_relative
+            kappa = usdot_relative()
+        kappa = np.asarray(kappa, float)
+        kmax = float(kappa.max())
+        b_minus = 0
+        if self.noise is not None:
+            b_minus = (max(up for _, up in self.noise.tmap.values())
+                       if self.noise.tmap else self.noise.b_minus)
+        cal = self._cal
+        costs = (inflated_costs(cal["y"], kappa, b_minus) if b_minus > 0
+                 else kappa[cal["y"] - 1])
+
+        cdf = self._cdf(X)
+        keys, cls_keys = self._keys(X, strata)
+        uniq, inverse = np.unique(keys, return_inverse=True)
+        thr = np.empty(len(uniq))
+        for j, key in enumerate(uniq):
+            cls_key = cls_keys[np.argmax(inverse == j)]
+            for mask_level in (cal["cell_keys"] == key, cal["class_keys"] == cls_key,
+                               np.ones(len(cal["scores"]), bool)):
+                if mask_level.sum() >= self.n_min or mask_level.all():
+                    thr[j] = crc_threshold(cal["scores"][mask_level],
+                                           costs[mask_level], kmax, beta)
+                    break
+        lam = thr[inverse]
+        lo, hi = interval_sets(cdf, lam)
+        if self.noise is not None:
+            lo, hi = self.noise.expand(lo, hi)
+        return lo, hi
+
+    # -- certificates (Thm 6 slack budget) --
+
+    def certificate(self, alpha: float = 0.1) -> list[Certificate]:
+        """Per-cell coverage certificates for all calibrated cells (observed strata).
+
+        New-stratum certificates additionally need the TV-slack diagnostics of
+        choir.shift (tv_slack_lcb); attach via shift tools in the experiments layer.
+        """
+        if self._cal is None:
+            raise RuntimeError("call calibrate() first")
+        out = []
+        delta = self.noise.delta if self.noise is not None else 0.0
+        for key in np.unique(self._cal["cell_keys"]):
+            n = int((self._cal["cell_keys"] == key).sum())
+            slacks = {}
+            if self.noise is not None:
+                slacks["noise"] = (delta, "N(T, delta) compatibility, declared")
+            out.append(Certificate(nominal=1 - alpha, slacks=slacks, cell=key, n_cal=n))
+        return out

choir/core/calibrate.py

@@ -0,0 +1,75 @@
+"""Split, Mondrian, and weighted conformal calibration (methods.tex Prop 1, Thm 2, Thm 4).
+
+All calibration consumes scores only; enforcing that partitions/weights were fit
+without calibration labels is the caller's contract (documented, and enforced by the
+high-level CertifiedOrdinal API which fits partitions on the training split only).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def conformal_quantile(scores: np.ndarray, alpha: float) -> float:
+    """The ceil((1-alpha)(n+1))-th smallest score; +inf if index exceeds n (Prop 1)."""
+    scores = np.asarray(scores, dtype=float)
+    n = len(scores)
+    if not 0.0 < alpha < 1.0:
+        raise ValueError("alpha must be in (0, 1)")
+    k = int(np.ceil((1.0 - alpha) * (n + 1)))
+    if k > n:
+        return np.inf
+    return float(np.partition(scores, k - 1)[k - 1])
+
+
+def split_calibrate(scores: np.ndarray, alpha: float) -> float:
+    """Marginal split conformal threshold (Proposition 1)."""
+    return conformal_quantile(scores, alpha)
+
+
+def mondrian_calibrate(
+    scores: np.ndarray,
+    groups: np.ndarray,
+    alpha: float,
+) -> dict:
+    """Per-group conformal thresholds (Theorem 2 / Theorem 4a).
+
+    groups: array of hashable group labels, same length as scores, produced by a
+    function fit independently of the calibration labels (split discipline).
+    Returns {group: threshold}. Groups absent at prediction time must be handled
+    by the caller's rollup rule (see choir.shift.rollup).
+    """
+    scores = np.asarray(scores, dtype=float)
+    groups = np.asarray(groups)
+    return {
+        g: conformal_quantile(scores[groups == g], alpha)
+        for g in np.unique(groups)
+    }
+
+
+def weighted_quantile(
+    scores: np.ndarray,
+    weights: np.ndarray,
+    test_weight: float,
+    alpha: float,
+) -> float:
+    """Weighted conformal threshold (Theorem 4b display equation).
+
+    q = inf{ t : sum_i w_i 1{S_i <= t} >= (1-alpha) * (sum_i w_i + w_test) },
+    with the test point's mass placed at +inf (conservative placement per
+    Tibshirani et al. 2019); +inf when the calibration mass cannot reach the target.
+    """
+    scores = np.asarray(scores, dtype=float)
+    weights = np.asarray(weights, dtype=float)
+    if np.any(weights < 0) or test_weight < 0:
+        raise ValueError("weights must be non-negative")
+    total = weights.sum() + test_weight
+    if total <= 0:
+        raise ValueError("all weights are zero")
+    order = np.argsort(scores, kind="stable")
+    csum = np.cumsum(weights[order])
+    target = (1.0 - alpha) * total
+    idx = np.searchsorted(csum, target, side="left")
+    if idx >= len(scores):
+        return np.inf
+    return float(scores[order][idx])

choir/core/intervals.py

@@ -0,0 +1,74 @@
+"""Interval prediction sets (methods.tex Definition 2, Lemma 1, Convention 1).
+
+C_lambda(x) = {k : s(x,k) <= lambda} is a contiguous interval by Lemma 1; if empty,
+Convention 1 returns the singleton argmin_k s(x,k) (this only enlarges sets, so every
+lower coverage bound is preserved).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from choir.core.scores import score_matrix
+
+
+def interval_sets(cdf: np.ndarray, lam: np.ndarray | float) -> tuple[np.ndarray, np.ndarray]:
+    """Return (lo, hi) 1-indexed inclusive interval endpoints per row.
+
+    lam may be a scalar or an (n,) vector of per-row thresholds (Mondrian use).
+    Never returns an empty set (Convention 1).
+    """
+    sm = score_matrix(cdf)  # (n, K)
+    lam = np.broadcast_to(np.asarray(lam, dtype=float), (sm.shape[0],))
+    member = sm <= lam[:, None]  # (n, K)
+
+    K = sm.shape[1]
+    idx = np.arange(1, K + 1)
+    lo = np.where(member.any(axis=1), np.where(member, idx, K + 1).min(axis=1), 0)
+    hi = np.where(member.any(axis=1), np.where(member, idx, 0).max(axis=1), 0)
+
+    empty = lo == 0
+    if empty.any():  # Convention 1
+        arg = sm[empty].argmin(axis=1) + 1
+        lo = lo.copy()
+        hi = hi.copy()
+        lo[empty] = arg
+        hi[empty] = arg
+
+    # Lemma 1 invariant: membership must be contiguous between lo and hi.
+    # (Cheap runtime check; guards against a non-monotone cdf slipping through.)
+    width = hi - lo + 1
+    if not np.array_equal(member.sum(axis=1)[~empty], width[~empty]):
+        raise AssertionError("non-contiguous set: cdf violates monotonicity")
+    return lo, hi
+
+
+def expand_intervals(
+    lo: np.ndarray, hi: np.ndarray, b_plus: int, b_minus: int, K: int
+) -> tuple[np.ndarray, np.ndarray]:
+    """Banded compatibility expansion (Definition 3): [lo - b_plus, hi + b_minus] ∩ Y.
+
+    b_plus guards over-reporting (reach downward); b_minus guards under-reporting
+    (reach upward). See methods.tex Assumption N.
+    """
+    if b_plus < 0 or b_minus < 0:
+        raise ValueError("band widths must be non-negative")
+    return np.maximum(lo - b_plus, 1), np.minimum(hi + b_minus, K)
+
+
+def expand_intervals_map(
+    lo: np.ndarray, hi: np.ndarray, tmap: dict[int, tuple[int, int]], K: int
+) -> tuple[np.ndarray, np.ndarray]:
+    """Category-dependent expansion (Remark 3.2).
+
+    tmap[k] = (down_k, up_k): a report k is compatible with truths [k - down_k, k + up_k].
+    The expanded interval is the union of T(k) over k in [lo, hi]; with interval T(k)
+    this is [min_k (k - down_k), max_k (k + up_k)] over k in [lo, hi].
+    """
+    lo_out = np.empty_like(lo)
+    hi_out = np.empty_like(hi)
+    for i, (a, b) in enumerate(zip(lo, hi)):
+        ks = range(int(a), int(b) + 1)
+        lo_out[i] = max(1, min(k - tmap[k][0] for k in ks))
+        hi_out[i] = min(K, max(k + tmap[k][1] for k in ks))
+    return lo_out, hi_out

choir/core/scores.py

@@ -0,0 +1,47 @@
+"""Ordinal cumulative score (methods.tex Definition 1).
+
+s(x, y) = max{ F(y-1 | x), 1 - F(y | x) }, with F(0|x) = 0, F(K|x) = 1.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def _validate_cdf(cdf: np.ndarray) -> np.ndarray:
+    """Validate an (n, K) conditional-CDF matrix: rows non-decreasing, last col 1."""
+    cdf = np.asarray(cdf, dtype=float)
+    if cdf.ndim != 2:
+        raise ValueError(f"cdf must be 2-D (n, K); got shape {cdf.shape}")
+    if np.any(np.diff(cdf, axis=1) < -1e-9):
+        raise ValueError("cdf rows must be non-decreasing in the category index")
+    if not np.allclose(cdf[:, -1], 1.0, atol=1e-6):
+        raise ValueError("cdf last column must equal 1")
+    return np.clip(cdf, 0.0, 1.0)
+
+
+def cdf_from_proba(proba: np.ndarray) -> np.ndarray:
+    """Cumulate an (n, K) class-probability matrix into a conditional CDF."""
+    proba = np.asarray(proba, dtype=float)
+    cdf = np.cumsum(proba, axis=1)
+    cdf /= cdf[:, -1:]  # renormalize against float drift
+    return cdf
+
+
+def score_matrix(cdf: np.ndarray) -> np.ndarray:
+    """All candidate-label scores: out[i, k-1] = s(x_i, k), k = 1..K.
+
+    Vectorized Definition 1: F(y-1) is the CDF shifted right with 0 prepended.
+    """
+    cdf = _validate_cdf(cdf)
+    below = np.concatenate([np.zeros((cdf.shape[0], 1)), cdf[:, :-1]], axis=1)
+    return np.maximum(below, 1.0 - cdf)
+
+
+def cumulative_score(cdf: np.ndarray, y: np.ndarray) -> np.ndarray:
+    """s(x_i, y_i) for observed labels y in {1..K} (1-indexed)."""
+    y = np.asarray(y)
+    if y.min() < 1 or y.max() > cdf.shape[1]:
+        raise ValueError("labels must be 1-indexed in {1..K}")
+    sm = score_matrix(cdf)
+    return sm[np.arange(len(y)), y - 1]

choir/crash/__init__.py

@@ -0,0 +1,4 @@
+from choir.crash.kabco import KABCO_LEVELS, kabco_to_int
+from choir.crash.costs import usdot_relative
+
+__all__ = ["KABCO_LEVELS", "kabco_to_int", "usdot_relative"]

choir/crash/costs.py

@@ -0,0 +1,21 @@
+"""Severity cost vectors for risk control (methods.tex §risk).
+
+usdot_relative: order-of-magnitude comprehensive-crash-cost scale relative to O=1,
+per the USDOT/FHWA VSL-based guidance. Exact dollar figures and citation year are
+pinned during E7 (verification memo §4 item 4); the guarantees only require kappa
+non-decreasing, and all E7 results are reported for the pinned vector.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def usdot_relative() -> np.ndarray:
+    """Relative comprehensive-cost scale (O, C, B, A, K), kappa(O)=1."""
+    return np.array([1.0, 20.0, 30.0, 150.0, 1500.0])
+
+
+def fatal_omission() -> np.ndarray:
+    """Indicator cost for the fatal-omission guarantee (Corollary 5c)."""
+    return np.array([0.0, 0.0, 0.0, 0.0, 1.0])

choir/crash/kabco.py

@@ -0,0 +1,29 @@
+"""KABCO ordinal scale utilities.
+
+y in {1..5}: 1=O (not injured), 2=C (possible), 3=B (non-incapacitating / suspected
+minor), 4=A (incapacitating / suspected serious), 5=K (fatal).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+KABCO_LEVELS = ("O", "C", "B", "A", "K")
+
+# CRIS Prsn_Injry_Sev_ID strings (TxDOT), verified against the 2017-2025 extract.
+CRIS_MAP = {
+    "Not Injured": 1,
+    "Possible Injury": 2,
+    "Non-Incapacitating Injury": 3,
+    "Incapacitating Injury": 4,
+    "Killed": 5,
+}
+
+
+def kabco_to_int(labels, mapping: dict | None = None) -> np.ndarray:
+    """Map string severity labels to 1..5; unmapped values (Unknown/None) become 0.
+
+    Rows with 0 must be dropped by the caller and counted in the attrition table.
+    """
+    m = mapping or CRIS_MAP
+    return np.array([m.get(v, 0) for v in labels], dtype=int)

choir/datasets/__init__.py

@@ -0,0 +1,11 @@
+"""Small public demo data so examples run without CRIS in under a minute.
+
+The bundled table is a deterministically generated SYNTHETIC sample that follows the
+public FARS/KABCO schema (no real records, no PII). It exists only to make the README
+and tutorials runnable anywhere. Swap in a real FARS extract by replacing demo_fars.csv
+with the same columns.
+"""
+
+from choir.datasets.loader import load_demo, DEMO_COLUMNS
+
+__all__ = ["load_demo", "DEMO_COLUMNS"]