choircert 0.1.0__tar.gz

choircert-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Virtual environments
+.venv/
+.buildenv/
+.testenv/
+.env/
+venv/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Docs build
+site/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# NOTE: src/choir/datasets/demo_fars.csv is a public FARS-schema demo (no PII)
+# and MUST stay tracked. Do not add a blanket *.csv ignore here.

choircert-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amir Rafe and Subasish Das, Texas State University
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

choircert-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: choircert
+Version: 0.1.0
+Summary: A certification layer for ordinal, safety-critical prediction: distribution-free validity, label-noise robustness, deployment-shift certificates, and severity-weighted risk control.
+Project-URL: Homepage, https://github.com/pozapas/choircert
+Project-URL: Repository, https://github.com/pozapas/choircert
+Project-URL: Issues, https://github.com/pozapas/choircert/issues
+Author-email: Amir Rafe <amir.rafe@txstate.edu>, Subasish Das <subasish@txstate.edu>
+License: MIT
+License-File: LICENSE
+Keywords: conformal prediction,crash severity,distribution-free inference,ordinal classification,risk control,trustworthy AI,uncertainty quantification
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Provides-Extra: benchmarks
+Requires-Dist: crepes<1.0,>=0.7; extra == 'benchmarks'
+Requires-Dist: mapie<2.0,>=1.0; extra == 'benchmarks'
+Requires-Dist: scikit-learn>=1.4; extra == 'benchmarks'
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: econ
+Requires-Dist: scipy>=1.10; extra == 'econ'
+Provides-Extra: maps
+Requires-Dist: matplotlib>=3.7; extra == 'maps'
+Provides-Extra: torch
+Requires-Dist: torch>=2.0; extra == 'torch'
+Description-Content-Type: text/markdown
+
+# CHOIR
+
+**A certification layer for ordinal, safety-critical prediction.** Distribution name
+on PyPI: `choircert`; import name: `choir`.
+
+Wrap any ordinal severity model and obtain finite-sample, distribution-free guarantees:
+contiguous ordinal prediction sets with marginal and group-conditional coverage
+(heterogeneity classes, jurisdiction-year strata), coverage on the *true* label under a
+declared banded reporting-noise assumption, deployment-shift transfer certificates, and
+severity-weighted risk control including a fatal-omission guarantee, all composable with
+an explicit slack budget.
+
+Every guarantee is a statement about prediction-set coverage or expected risk under a
+declared sampling assumption. The package estimates no causal quantities.
+
+## Install
+
+```
+pip install choircert            # core (numpy only)
+pip install "choircert[torch]"   # + the DLCON deep base model
+pip install "choircert[econ,maps]"  # + scipy models, county maps
+```
+
+## Quickstart
+
+```python
+import numpy as np
+from choir import CertifiedOrdinal, NoiseModel
+
+cert = CertifiedOrdinal(
+    base=any_model_with_predict_proba,     # ordered logit, XGBoost, deep net, ...
+    partition=latent_class_assigner,       # fit on the training split (or None)
+    noise=NoiseModel.kabco(delta=0.02),    # declared band; swept in sensitivity curves
+    n_min=1000,                            # per-cell floor with automatic rollup
+)
+cert.fit(X_train, y_train).calibrate(X_cal, y_reported)
+
+lo, hi = cert.predict_set(X_new, alpha=0.10)      # contiguous KABCO intervals
+lo, hi = cert.predict_set_risk(X_new, beta=0.05)  # severity-cost risk control
+for c in cert.certificate(alpha=0.10):
+    print(c.cell, c.n_cal, c.floor)               # per-cell slack budget
+```
+
+Runnable end to end on bundled synthetic data:
+
+```python
+from choir.datasets import load_demo
+rows, y, cols = load_demo()   # FARS-schema synthetic sample, no PII, no download
+```
+
+`python examples/demo.py` runs in seconds. `pytest tests/` reproduces every guarantee
+on simulated data: marginal validity, class-conditional coverage, banded-noise transfer,
+group-weighted shift, weighted transfer, cost risk control, and composition.
+
+## How it compares
+
+Generic conformal toolkits (MAPIE, crepes, puncc) provide split and Mondrian machinery.
+They are correct and attain marginal coverage. What they do not provide for an ordinal,
+safety-critical target is contiguity, a guarantee on the true (noisy) label, and a
+fatal-omission guarantee. The table below is produced by `benchmarks/vs_mapie_crepes.py`
+on the bundled demo at a nominal 0.90 level.
+
+| method | coverage | avg set size | contiguous sets | true-label guarantee | fatal-omission guarantee |
+|--------|:--------:|:------------:|:---------------:|:--------------------:|:------------------------:|
+| CHOIR  | 0.895    | 2.19         | yes (by construction) | yes            | yes                      |
+| MAPIE  | 0.899    | 2.22         | 99%             | no                   | no                       |
+| crepes | 0.899    | 2.22         | 99%             | no                   | no                       |
+
+The coverage is deliberately the same; the guarantee is the same theorem. The difference
+is that CHOIR's sets are always contiguous intervals on the KABCO scale, and that CHOIR
+additionally transfers coverage to the true injury under a declared band and bounds the
+probability of excluding a true fatality. On this demo, the generic toolkits return a
+non-contiguous set about one percent of the time, which is not an operationally meaningful
+"B or worse" statement.
+
+## What is guaranteed
+
+The four guarantees and their proofs are in the companion paper (Transportation Research
+Part B, under review). Each is finite-sample and distribution-free in the wrapped model:
+class-conditional coverage (validity for any partition, oracle efficiency for a good one),
+true-label coverage `1 - alpha - delta` under a banded compatibility assumption,
+deployment transfer certificates reported as (nominal level, slack lower confidence bound,
+parametric slack estimate), and severity-cost risk control including the fatal-omission
+bound. The composition theorem combines them with an additive, assumption-attributable
+slack budget.
+
+## Citing
+
+See `CITATION.cff`. Cite both the software (Zenodo DOI, on release) and the paper.
+
+## License
+
+MIT.

choircert-0.1.0/README.md

@@ -0,0 +1,93 @@
+# CHOIR
+
+**A certification layer for ordinal, safety-critical prediction.** Distribution name
+on PyPI: `choircert`; import name: `choir`.
+
+Wrap any ordinal severity model and obtain finite-sample, distribution-free guarantees:
+contiguous ordinal prediction sets with marginal and group-conditional coverage
+(heterogeneity classes, jurisdiction-year strata), coverage on the *true* label under a
+declared banded reporting-noise assumption, deployment-shift transfer certificates, and
+severity-weighted risk control including a fatal-omission guarantee, all composable with
+an explicit slack budget.
+
+Every guarantee is a statement about prediction-set coverage or expected risk under a
+declared sampling assumption. The package estimates no causal quantities.
+
+## Install
+
+```
+pip install choircert            # core (numpy only)
+pip install "choircert[torch]"   # + the DLCON deep base model
+pip install "choircert[econ,maps]"  # + scipy models, county maps
+```
+
+## Quickstart
+
+```python
+import numpy as np
+from choir import CertifiedOrdinal, NoiseModel
+
+cert = CertifiedOrdinal(
+    base=any_model_with_predict_proba,     # ordered logit, XGBoost, deep net, ...
+    partition=latent_class_assigner,       # fit on the training split (or None)
+    noise=NoiseModel.kabco(delta=0.02),    # declared band; swept in sensitivity curves
+    n_min=1000,                            # per-cell floor with automatic rollup
+)
+cert.fit(X_train, y_train).calibrate(X_cal, y_reported)
+
+lo, hi = cert.predict_set(X_new, alpha=0.10)      # contiguous KABCO intervals
+lo, hi = cert.predict_set_risk(X_new, beta=0.05)  # severity-cost risk control
+for c in cert.certificate(alpha=0.10):
+    print(c.cell, c.n_cal, c.floor)               # per-cell slack budget
+```
+
+Runnable end to end on bundled synthetic data:
+
+```python
+from choir.datasets import load_demo
+rows, y, cols = load_demo()   # FARS-schema synthetic sample, no PII, no download
+```
+
+`python examples/demo.py` runs in seconds. `pytest tests/` reproduces every guarantee
+on simulated data: marginal validity, class-conditional coverage, banded-noise transfer,
+group-weighted shift, weighted transfer, cost risk control, and composition.
+
+## How it compares
+
+Generic conformal toolkits (MAPIE, crepes, puncc) provide split and Mondrian machinery.
+They are correct and attain marginal coverage. What they do not provide for an ordinal,
+safety-critical target is contiguity, a guarantee on the true (noisy) label, and a
+fatal-omission guarantee. The table below is produced by `benchmarks/vs_mapie_crepes.py`
+on the bundled demo at a nominal 0.90 level.
+
+| method | coverage | avg set size | contiguous sets | true-label guarantee | fatal-omission guarantee |
+|--------|:--------:|:------------:|:---------------:|:--------------------:|:------------------------:|
+| CHOIR  | 0.895    | 2.19         | yes (by construction) | yes            | yes                      |
+| MAPIE  | 0.899    | 2.22         | 99%             | no                   | no                       |
+| crepes | 0.899    | 2.22         | 99%             | no                   | no                       |
+
+The coverage is deliberately the same; the guarantee is the same theorem. The difference
+is that CHOIR's sets are always contiguous intervals on the KABCO scale, and that CHOIR
+additionally transfers coverage to the true injury under a declared band and bounds the
+probability of excluding a true fatality. On this demo, the generic toolkits return a
+non-contiguous set about one percent of the time, which is not an operationally meaningful
+"B or worse" statement.
+
+## What is guaranteed
+
+The four guarantees and their proofs are in the companion paper (Transportation Research
+Part B, under review). Each is finite-sample and distribution-free in the wrapped model:
+class-conditional coverage (validity for any partition, oracle efficiency for a good one),
+true-label coverage `1 - alpha - delta` under a banded compatibility assumption,
+deployment transfer certificates reported as (nominal level, slack lower confidence bound,
+parametric slack estimate), and severity-cost risk control including the fatal-omission
+bound. The composition theorem combines them with an additive, assumption-attributable
+slack budget.
+
+## Citing
+
+See `CITATION.cff`. Cite both the software (Zenodo DOI, on release) and the paper.
+
+## License
+
+MIT.

choircert-0.1.0/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "choircert"
+version = "0.1.0"
+description = "A certification layer for ordinal, safety-critical prediction: distribution-free validity, label-noise robustness, deployment-shift certificates, and severity-weighted risk control."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+  { name = "Amir Rafe", email = "amir.rafe@txstate.edu" },
+  { name = "Subasish Das", email = "subasish@txstate.edu" },
+]
+keywords = ["conformal prediction", "ordinal classification", "uncertainty quantification",
+            "distribution-free inference", "risk control", "crash severity", "trustworthy AI"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: Mathematics",
+]
+dependencies = ["numpy>=1.24"]
+
+[project.urls]
+Homepage = "https://github.com/pozapas/choircert"
+Repository = "https://github.com/pozapas/choircert"
+Issues = "https://github.com/pozapas/choircert/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "hypothesis>=6", "ruff>=0.5"]
+torch = ["torch>=2.0"]
+econ = ["scipy>=1.10"]
+maps = ["matplotlib>=3.7"]
+# Third-party conformal toolkits compared against CHOIR in
+# benchmarks/vs_mapie_crepes.py (paper Table 7). Both bounds are load-bearing:
+# the script targets MAPIE's v1.x SplitConformalClassifier API
+# (conformalize/predict_set), which replaced the v0.x MapieClassifier API, so
+# <2.0 guards against a future rename and >=1.0 excludes the old path. crepes
+# >=0.7 is the line whose WrapClassifier.predict_set accepts the `labels=`
+# keyword the script passes.
+benchmarks = ["mapie>=1.0,<2.0", "crepes>=0.7,<1.0", "scikit-learn>=1.4"]
+
+# Ship the bundled demo table even though the repo .gitignore excludes *.csv
+# (PII guard). `artifacts` forces it into BOTH sdist and wheel regardless of
+# VCS-ignore status, so `python -m build` (wheel-from-sdist) and fresh clones
+# both carry it. See RELEASE.md.
+[tool.hatch.build]
+artifacts = ["src/choir/datasets/demo_fars.csv"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/choir"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/choir", "tests", "README.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"

choircert-0.1.0/src/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"

choircert-0.1.0/src/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

choircert-0.1.0/src/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])