riskaudit 0.1.1__py3-none-any.whl

riskaudit/__init__.py

@@ -0,0 +1,4 @@
+from riskaudit._config import SEED
+
+__all__ = ["SEED"]
+__version__ = "0.1.0"

riskaudit/_config.py

@@ -0,0 +1,12 @@
+import os
+from pathlib import Path
+
+SEED = 2026
+
+PROJECT_ROOT = Path(os.environ.get("RISKAUDIT_ROOT", Path.cwd()))
+DATA_DIR = PROJECT_ROOT / "data"
+ARTIFACTS_DIR = PROJECT_ROOT / "artifacts"
+
+RAW_DIR = DATA_DIR / "raw"
+PROCESSED_DIR = DATA_DIR / "processed"
+SYNTHETIC_DIR = DATA_DIR / "synthetic"

riskaudit/audit/__init__.py

@@ -0,0 +1,24 @@
+from riskaudit.audit._common import SurveyDesign
+from riskaudit.audit.ablation import AblationResult, ablation
+from riskaudit.audit.capture import CaptureResult, top_k_capture
+from riskaudit.audit.curves import CurveResult, label_choice_curve
+from riskaudit.audit.lift import LiftResult, incremental_lift
+from riskaudit.audit.reclassification import reclassification
+from riskaudit.audit.report import audit_report
+from riskaudit.audit.rtm import RTMResult, regression_to_mean
+
+__all__ = [
+    "AblationResult",
+    "CaptureResult",
+    "CurveResult",
+    "LiftResult",
+    "RTMResult",
+    "SurveyDesign",
+    "ablation",
+    "audit_report",
+    "incremental_lift",
+    "label_choice_curve",
+    "reclassification",
+    "regression_to_mean",
+    "top_k_capture",
+]

riskaudit/audit/_common.py

@@ -0,0 +1,107 @@
+import warnings
+from dataclasses import dataclass
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+
+@dataclass
+class SurveyDesign:
+    """Stratum and PSU labels for design-based (cluster) bootstrap resampling.
+
+    Pass one to the CI-bearing audit functions to resample PSUs within strata
+    (VARSTR/VARPSU) instead of individual rows, so the interval reflects the
+    survey design. Strata with a single PSU are held fixed (their variance
+    contribution is zero), and a warning is emitted when that happens.
+    """
+
+    strata: np.ndarray
+    psu: np.ndarray
+
+    def __post_init__(self):
+        self.strata = np.asarray(self.strata)
+        self.psu = np.asarray(self.psu)
+        singles = sum(
+            np.unique(self.psu[self.strata == s]).size < 2 for s in np.unique(self.strata)
+        )
+        if singles:
+            warnings.warn(
+                f"{singles} stratum(s) have a single PSU and are held fixed; their variance "
+                "contribution is zero, so the CI is biased low. Consider collapsing strata.",
+                stacklevel=2,
+            )
+
+
+def check_inputs(**arrays: ArrayLike) -> None:
+    """Validate that public inputs are finite and equally long (fail at the boundary)."""
+    n = None
+    for name, a in arrays.items():
+        arr = np.asarray(a, dtype=float)
+        if not np.isfinite(arr).all():
+            raise ValueError(f"{name} contains NaN or inf")
+        if n is None:
+            n = arr.shape[0]
+        elif arr.shape[0] != n:
+            raise ValueError(f"length mismatch: {name} has {arr.shape[0]}, expected {n}")
+
+
+def to_float(x: ArrayLike) -> np.ndarray:
+    return np.asarray(x, dtype=float)
+
+
+def weights_or_ones(weights: ArrayLike | None, n: int) -> np.ndarray:
+    return np.ones(n) if weights is None else np.asarray(weights, dtype=float)
+
+
+def topk_mask(scores: np.ndarray, weights: np.ndarray, k: float) -> np.ndarray:
+    """Boolean mask of the highest-scoring units whose weight first reaches ``k``.
+
+    Ties are broken by row order (stable sort), so with discretized scores the
+    exact top-``k`` membership can depend on the input order.
+    """
+    order = np.argsort(-scores, kind="stable")
+    cumw = np.cumsum(weights[order])
+    j = int(np.searchsorted(cumw, k * cumw[-1]))
+    mask = np.zeros(scores.shape[0], dtype=bool)
+    mask[order[: j + 1]] = True
+    return mask
+
+
+def wmean(x: np.ndarray, w: np.ndarray) -> float:
+    return float(np.sum(w * x) / np.sum(w))
+
+
+def weighted_capture(scores: np.ndarray, need: np.ndarray, weights: np.ndarray, k: float) -> float:
+    """Weighted share of total need falling in the top-``k`` (by weight) of ``scores``."""
+    mask = topk_mask(scores, weights, k)
+    wn = weights * need
+    return float(wn[mask].sum() / wn.sum())
+
+
+def _cluster_indices(rng, design: SurveyDesign) -> np.ndarray:
+    parts = []
+    for st in np.unique(design.strata):
+        rows = np.where(design.strata == st)[0]
+        psus = np.unique(design.psu[rows])
+        if psus.size < 2:
+            parts.append(rows)
+            continue
+        for c in rng.choice(psus, size=psus.size, replace=True):
+            parts.append(rows[design.psu[rows] == c])
+    return np.concatenate(parts)
+
+
+def boot_ci(stat, n: int, n_boot: int, seed: int, design: SurveyDesign | None = None):
+    """Percentile CI from a seeded bootstrap of ``stat``.
+
+    Resamples rows uniformly, or PSUs within strata when a ``design`` is given.
+    The seed is fixed, so CIs of different metrics in the same report share the
+    same resamples (deterministic, but their sampling errors are correlated).
+    """
+    rng = np.random.default_rng(seed)
+
+    def draw():
+        return rng.integers(0, n, n) if design is None else _cluster_indices(rng, design)
+
+    vals = np.array([stat(draw()) for _ in range(n_boot)])
+    return float(np.nanpercentile(vals, 2.5)), float(np.nanpercentile(vals, 97.5))

riskaudit/audit/ablation.py

@@ -0,0 +1,99 @@
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+from numpy.typing import ArrayLike
+from sklearn.metrics import r2_score, roc_auc_score
+from sklearn.model_selection import KFold
+
+from riskaudit._config import SEED
+from riskaudit.audit._common import to_float, weighted_capture, weights_or_ones
+
+
+@dataclass
+class AblationResult:
+    global_delta: pd.DataFrame
+    capture_delta: pd.DataFrame
+
+
+def _perf(y: np.ndarray, pred: np.ndarray, w: np.ndarray) -> float:
+    if np.isin(np.unique(y), [0, 1]).all():
+        return float(roc_auc_score(y, pred, sample_weight=w))
+    return float(r2_score(y, pred, sample_weight=w))
+
+
+def ablation(
+    fit_fn: Callable[[pd.DataFrame, ArrayLike], object],
+    X: pd.DataFrame,
+    y: ArrayLike,
+    feature_groups: Mapping[str, Sequence[str]],
+    need: ArrayLike | None = None,
+    k: float = 0.10,
+    weights: ArrayLike | None = None,
+    cv: int = 5,
+    seed: int = SEED,
+) -> AblationResult:
+    r"""Refit without each feature group; contrast global loss with capture loss.
+
+    Predictions are **cross-fitted** (``cv``-fold): every row is scored by a model
+    that did not train on it, so the deltas reflect generalization, not in-sample
+    memorization. For each group :math:`g` the model is refit on :math:`X` with the
+    columns of :math:`g` removed and compared to the full-feature model on:
+
+    - :math:`\Delta\text{global}` — change in cross-fitted performance (R\ :sup:`2`
+      or AUC) predicting the target :math:`y`;
+    - :math:`\Delta\text{capture}` — change in weighted top-``k`` capture of
+      ``need`` (the independent need measure; defaults to the target ``y``).
+
+    The expected finding for a spend target with ``need`` set to measured distress:
+    dropping the mental-health group barely moves :math:`\Delta\text{global}` yet
+    collapses :math:`\Delta\text{capture}`.
+
+    Parameters
+    ----------
+    fit_fn : callable ``(X, y) -> fitted model with .predict``
+        Trains one model; called once per fold per ablation with the same settings.
+    X : pandas.DataFrame of shape (n, p)
+        Feature matrix.
+    y : array-like of shape (n,)
+        Target the model is trained on.
+    feature_groups : mapping of str to sequence of str
+        Group name to its column names in ``X``.
+    need : array-like of shape (n,), optional
+        Independent need measure for the capture delta; defaults to ``y``.
+    k : float, default 0.10
+        Top fraction for the capture comparison.
+    weights : array-like of shape (n,), optional
+        Survey weights; all ones when omitted.
+    cv : int, default 5
+        Number of cross-fitting folds.
+    seed : int, default SEED
+        Fold shuffle seed.
+
+    Returns
+    -------
+    AblationResult
+        Per-group global and capture deltas.
+    """
+    w = weights_or_ones(weights, len(X))
+    yv = np.asarray(y)
+    nd = to_float(y if need is None else need)
+    folds = list(KFold(max(2, min(cv, len(X))), shuffle=True, random_state=seed).split(X))
+
+    def cross_fit(xd: pd.DataFrame) -> np.ndarray:
+        pred = np.empty(len(xd))
+        for tr, te in folds:
+            model = fit_fn(xd.iloc[tr], yv[tr])
+            pred[te] = np.asarray(model.predict(xd.iloc[te]), dtype=float)
+        return pred
+
+    p0 = cross_fit(X)
+    g0, c0 = _perf(yv, p0, w), weighted_capture(p0, nd, w, k)
+
+    gd, cd = {}, {}
+    for name, cols in feature_groups.items():
+        pg = cross_fit(X.drop(columns=list(cols)))
+        gd[name] = g0 - _perf(yv, pg, w)
+        cd[name] = c0 - weighted_capture(pg, nd, w, k)
+    return AblationResult(pd.DataFrame({"delta": gd}), pd.DataFrame({"delta": cd}))

riskaudit/audit/capture.py

@@ -0,0 +1,83 @@
+from dataclasses import dataclass
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+from riskaudit._config import SEED
+from riskaudit.audit._common import (
+    SurveyDesign,
+    boot_ci,
+    check_inputs,
+    to_float,
+    weighted_capture,
+    weights_or_ones,
+)
+
+
+@dataclass
+class CaptureResult:
+    value: float
+    ci: tuple[float, float]
+    k: float
+    baseline: float  # capture expected from a random score (= k)
+    oracle: float  # capture from ranking by need itself (the achievable ceiling)
+
+
+def top_k_capture(
+    scores: ArrayLike,
+    need: ArrayLike,
+    k: float = 0.10,
+    weights: ArrayLike | None = None,
+    n_boot: int = 1000,
+    design: SurveyDesign | None = None,
+) -> CaptureResult:
+    r"""Weighted share of total need captured by the top-``k`` of ``scores``.
+
+    Units are ranked by ``scores`` descending and the top ``k`` fraction *by
+    weight* is selected. The statistic is the weighted share of total need that
+    falls in that group,
+
+    .. math::
+        C_k \;=\; \frac{\sum_{i \in T_k} w_i\, n_i}{\sum_i w_i\, n_i},
+
+    where :math:`T_k` is the highest-scoring set whose cumulative weight first
+    reaches a fraction :math:`k` of the total weight, :math:`n_i` is need and
+    :math:`w_i` the survey weight. A model that ranks by true need attains a
+    high :math:`C_k`; the gap between a spend-ranked and a need-ranked model is
+    the label-choice cost this toolkit measures.
+
+    Parameters
+    ----------
+    scores : array-like of shape (n,)
+        Model score per unit; higher means higher predicted priority.
+    need : array-like of shape (n,)
+        Independent measure of realized need on the same units.
+    k : float, default 0.10
+        Top fraction, by weight, to select.
+    weights : array-like of shape (n,), optional
+        Survey weights; treated as all ones when omitted.
+    n_boot : int, default 1000
+        Weighted bootstrap resamples for the confidence interval.
+    design : SurveyDesign, optional
+        When given, the CI resamples PSUs within strata (VARSTR/VARPSU) instead
+        of rows, for a design-based interval.
+
+    Returns
+    -------
+    CaptureResult
+        ``value``, its 95% ``ci``, the random-score ``baseline`` (= ``k``), and
+        the ``oracle`` (ranking by ``need`` itself). Read ``value`` against both:
+        a raw capture is uninterpretable without its floor and ceiling.
+    """
+    s = to_float(scores)
+    nd = to_float(need)
+    w = weights_or_ones(weights, s.shape[0])
+    check_inputs(scores=s, need=nd, weights=w)
+
+    def stat(idx: np.ndarray) -> float:
+        return weighted_capture(s[idx], nd[idx], w[idx], k)
+
+    value = stat(np.arange(s.shape[0]))
+    ci = boot_ci(stat, s.shape[0], n_boot, SEED, design)
+    oracle = weighted_capture(nd, nd, w, k)
+    return CaptureResult(value, ci, k, k, oracle)

riskaudit/audit/curves.py

@@ -0,0 +1,101 @@
+from dataclasses import dataclass
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+from riskaudit._config import SEED
+from riskaudit.audit._common import (
+    SurveyDesign,
+    _cluster_indices,
+    check_inputs,
+    to_float,
+    weights_or_ones,
+)
+
+
+@dataclass
+class CurveResult:
+    percentile: np.ndarray
+    need_mean: np.ndarray
+    need_lo: np.ndarray
+    need_hi: np.ndarray
+
+
+def label_choice_curve(
+    scores: ArrayLike,
+    need: ArrayLike,
+    weights: ArrayLike | None = None,
+    bins: int = 20,
+    design: SurveyDesign | None = None,
+    n_boot: int = 1000,
+) -> CurveResult:
+    r"""Mean observed need across score percentiles, Obermeyer-style.
+
+    Units are grouped into ``bins`` equal-weight strata of the score, and each
+    stratum's weighted mean need is reported,
+
+    .. math::
+        \bar{n}_b \;=\; \frac{\sum_{i \in b} w_i\, n_i}{\sum_{i \in b} w_i}.
+
+    A model that ranks by true need yields a clean monotone rise; label-choice
+    bias shows as units with high need sitting at low score percentiles. The band
+    is a percentile bootstrap — a design-based cluster bootstrap when ``design``
+    is given, otherwise a row bootstrap.
+
+    Parameters
+    ----------
+    scores : array-like of shape (n,)
+        Model score per unit.
+    need : array-like of shape (n,)
+        Observed need on the same units.
+    weights : array-like of shape (n,), optional
+        Survey weights; all ones when omitted.
+    bins : int, default 20
+        Number of equal-weight score strata.
+    design : SurveyDesign, optional
+        When given, the band resamples PSUs within strata (VARSTR/VARPSU).
+    n_boot : int, default 1000
+        Bootstrap resamples for the band.
+
+    Returns
+    -------
+    CurveResult
+        Per-bin score percentile, mean need, and its 95% band.
+    """
+    s = to_float(scores)
+    nd = to_float(need)
+    w = weights_or_ones(weights, s.shape[0])
+    check_inputs(scores=s, need=nd, weights=w)
+
+    order = np.argsort(s, kind="stable")
+    edges = np.linspace(0, w[order].sum(), bins + 1)
+    label = np.empty(s.shape[0], dtype=int)
+    label[order] = np.clip(
+        np.searchsorted(edges, np.cumsum(w[order]), side="left") - 1, 0, bins - 1
+    )
+
+    def bin_means(idx: np.ndarray) -> np.ndarray:
+        out = np.full(bins, np.nan)
+        lab = label[idx]
+        for b in range(bins):
+            sel = idx[lab == b]
+            if sel.size:
+                out[b] = np.sum(w[sel] * nd[sel]) / np.sum(w[sel])
+        return out
+
+    mean = bin_means(np.arange(s.shape[0]))
+    pct = (np.arange(bins) + 0.5) / bins * 100
+
+    rng = np.random.default_rng(SEED)
+
+    def draw():
+        return (
+            rng.integers(0, s.shape[0], s.shape[0])
+            if design is None
+            else _cluster_indices(rng, design)
+        )
+
+    boot = np.array([bin_means(draw()) for _ in range(n_boot)])
+    lo = np.nanpercentile(boot, 2.5, axis=0)
+    hi = np.nanpercentile(boot, 97.5, axis=0)
+    return CurveResult(pct, mean, lo, hi)

riskaudit/audit/lift.py

@@ -0,0 +1,98 @@
+from dataclasses import dataclass
+
+from numpy.typing import ArrayLike
+
+from riskaudit._config import SEED
+from riskaudit.audit._common import (
+    SurveyDesign,
+    boot_ci,
+    check_inputs,
+    to_float,
+    topk_mask,
+    weights_or_ones,
+    wmean,
+)
+
+
+@dataclass
+class LiftResult:
+    value: float
+    ci: tuple[float, float]
+    residual_distressed: float
+    residual_other: float
+
+
+def incremental_lift(
+    y_t1: ArrayLike,
+    y_pred: ArrayLike,
+    distress: ArrayLike,
+    scores: ArrayLike,
+    k: float = 0.10,
+    weights: ArrayLike | None = None,
+    n_boot: int = 1000,
+    design: SurveyDesign | None = None,
+) -> LiftResult:
+    r"""Incremental need lift in the low-score tail (the contribution metric).
+
+    Among the units a model *deprioritizes* — those outside the top ``k`` of
+    ``scores`` — this contrasts how much more future need distressed people
+    generated than the model predicted, versus everyone else in that tail:
+
+    .. math::
+        \text{Lift}_k \;=\;
+        \frac{\sum_{i \in L} w_i d_i r_i}{\sum_{i \in L} w_i d_i}
+        \;-\;
+        \frac{\sum_{i \in L} w_i (1-d_i) r_i}{\sum_{i \in L} w_i (1-d_i)},
+
+    where :math:`L` is the deprioritized tail, :math:`d_i` marks measured
+    distress, and :math:`r_i = y_{i,t+1} - \hat y_i` is the realized residual of
+    the outcome the model targets. A positive lift means the model was blind to
+    real downstream need concentrated in the distressed — the non-circular core
+    of the argument, since :math:`y_{t+1}` is the model's own currency, not the
+    distress measure (``docs/methods.md`` §2).
+
+    Parameters
+    ----------
+    y_t1 : array-like of shape (n,)
+        Realized outcome at ``t+1`` (the spending/utilization the model targets).
+    y_pred : array-like of shape (n,)
+        The model's prediction of that outcome.
+    distress : array-like of shape (n,)
+        1 where measured need is present, 0 otherwise.
+    scores : array-like of shape (n,)
+        Model risk score defining the priority set.
+    k : float, default 0.10
+        Top fraction, by weight; its complement is the deprioritized tail.
+    weights : array-like of shape (n,), optional
+        Survey weights; all ones when omitted.
+    n_boot : int, default 1000
+        Bootstrap resamples for the confidence interval.
+    design : SurveyDesign, optional
+        When given, the CI resamples PSUs within strata (VARSTR/VARPSU) instead
+        of rows, for a design-based interval.
+
+    Returns
+    -------
+    LiftResult
+        The lift, its 95% ``ci``, and the two tail residual means.
+    """
+    y = to_float(y_t1)
+    p = to_float(y_pred)
+    d = to_float(distress)
+    s = to_float(scores)
+    w = weights_or_ones(weights, y.shape[0])
+    check_inputs(y_t1=y, y_pred=p, distress=d, scores=s, weights=w)
+    r = y - p
+
+    def stat(idx) -> float:
+        tail = ~topk_mask(s[idx], w[idx], k)
+        di = d[idx]
+        one, zero = tail & (di == 1), tail & (di == 0)
+        return wmean(r[idx][one], w[idx][one]) - wmean(r[idx][zero], w[idx][zero])
+
+    tail = ~topk_mask(s, w, k)
+    one, zero = tail & (d == 1), tail & (d == 0)
+    rd = wmean(r[one], w[one])
+    ro = wmean(r[zero], w[zero])
+    ci = boot_ci(stat, y.shape[0], n_boot, SEED, design)
+    return LiftResult(float(rd - ro), ci, float(rd), float(ro))

riskaudit/audit/reclassification.py

@@ -0,0 +1,54 @@
+import pandas as pd
+from numpy.typing import ArrayLike
+
+from riskaudit.audit._common import check_inputs, to_float, topk_mask, weights_or_ones
+
+
+def reclassification(
+    scores_a: ArrayLike,
+    scores_b: ArrayLike,
+    k: float = 0.10,
+    weights: ArrayLike | None = None,
+) -> pd.DataFrame:
+    r"""Who enters and leaves the top-``k`` when the label switches from A to B.
+
+    Let :math:`T_k^A` and :math:`T_k^B` be the top-``k`` sets (by weight) under
+    scores A and B. The result is the weighted 2x2 contingency of membership,
+
+    ==================  ================  ==================
+    .                   in :math:`T_k^B`  not in :math:`T_k^B`
+    ==================  ================  ==================
+    in :math:`T_k^A`    stay              dropped
+    not in :math:`T_k^A`  added           out
+    ==================  ================  ==================
+
+    ``added`` are the units a need-based label would prioritize that a
+    spend-based one misses — the population cost of the label choice.
+
+    Parameters
+    ----------
+    scores_a, scores_b : array-like of shape (n,)
+        Scores under label A and label B for the same units.
+    k : float, default 0.10
+        Top fraction, by weight.
+    weights : array-like of shape (n,), optional
+        Survey weights; all ones when omitted.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Weighted counts and shares for stay / dropped / added / out.
+    """
+    a = to_float(scores_a)
+    b = to_float(scores_b)
+    w = weights_or_ones(weights, a.shape[0])
+    check_inputs(scores_a=a, scores_b=b, weights=w)
+    ta = topk_mask(a, w, k)
+    tb = topk_mask(b, w, k)
+    cells = {"stay": ta & tb, "dropped": ta & ~tb, "added": ~ta & tb, "out": ~ta & ~tb}
+    total = w.sum()
+    rows = {
+        name: {"weight": float(w[m].sum()), "share": float(w[m].sum() / total)}
+        for name, m in cells.items()
+    }
+    return pd.DataFrame(rows).T[["weight", "share"]]

riskaudit/audit/report.py

@@ -0,0 +1,85 @@
+import base64
+import io
+from pathlib import Path
+from typing import Any
+
+import matplotlib
+
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt  # noqa: E402
+import pandas as pd  # noqa: E402
+
+from riskaudit.audit.ablation import AblationResult  # noqa: E402
+from riskaudit.audit.capture import CaptureResult  # noqa: E402
+from riskaudit.audit.curves import CurveResult  # noqa: E402
+from riskaudit.audit.lift import LiftResult  # noqa: E402
+from riskaudit.audit.rtm import RTMResult  # noqa: E402
+
+_STYLE = (
+    "body{font-family:system-ui,sans-serif;margin:2rem;max-width:820px;line-height:1.5}"
+    "table{border-collapse:collapse;margin:.5rem 0}td,th{border:1px solid #ccc;padding:4px 10px}"
+    "img{max-width:100%}"
+)
+
+
+def _fig_uri(fig) -> str:
+    buf = io.BytesIO()
+    fig.savefig(buf, format="png", bbox_inches="tight", dpi=90)
+    plt.close(fig)
+    return "data:image/png;base64," + base64.b64encode(buf.getvalue()).decode()
+
+
+def _render(name: str, r: Any) -> str:
+    if isinstance(r, CaptureResult):
+        return (
+            f"<p><b>{name}</b>: top-{r.k:.0%} capture = {r.value:.1%} "
+            f"(95% CI {r.ci[0]:.1%}–{r.ci[1]:.1%}; "
+            f"floor {r.baseline:.1%}, oracle {r.oracle:.1%})</p>"
+        )
+    if isinstance(r, RTMResult):
+        return (
+            f"<p><b>{name}</b>: observed drop {r.observed_drop:.3g}, RTM-expected "
+            f"{r.rtm_expected_drop:.3g}, RTM share {r.rtm_share:.1%} "
+            f"(95% CI {r.ci[0]:.1%}–{r.ci[1]:.1%})</p>"
+        )
+    if isinstance(r, LiftResult):
+        return (
+            f"<p><b>{name}</b>: incremental lift = {r.value:.3g} "
+            f"(distressed residual {r.residual_distressed:.3g} vs "
+            f"{r.residual_other:.3g}; 95% CI {r.ci[0]:.3g}–{r.ci[1]:.3g})</p>"
+        )
+    if isinstance(r, CurveResult):
+        fig, ax = plt.subplots(figsize=(5, 3))
+        ax.plot(r.percentile, r.need_mean, marker="o")
+        ax.fill_between(r.percentile, r.need_lo, r.need_hi, alpha=0.2)
+        ax.set_xlabel("score percentile")
+        ax.set_ylabel("mean need")
+        ax.set_title(name)
+        return f'<img src="{_fig_uri(fig)}" alt="{name}">'
+    if isinstance(r, AblationResult):
+        return (
+            f"<h3>{name}</h3><h4>global Δ</h4>{r.global_delta.to_html()}"
+            f"<h4>capture Δ</h4>{r.capture_delta.to_html()}"
+        )
+    if isinstance(r, pd.DataFrame):
+        return f"<h3>{name}</h3>{r.to_html()}"
+    return f"<p><b>{name}</b>: {r}</p>"
+
+
+def audit_report(results: dict[str, Any], out_html: str | Path) -> Path:
+    """Render audit results into one self-contained HTML file.
+
+    Takes the objects returned by the audit functions (keyed by name) and
+    writes a single HTML document with every figure inlined as a data URI, so
+    it opens with no external assets. Returns the written path.
+    """
+    body = "\n".join(_render(k, v) for k, v in results.items())
+    html = (
+        f"<!doctype html><html><head><meta charset='utf-8'>"
+        f"<title>riskaudit report</title><style>{_STYLE}</style></head>"
+        f"<body><h1>riskaudit report</h1>{body}</body></html>"
+    )
+    out = Path(out_html)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(html, encoding="utf-8")
+    return out