biohcc

Probe measurement primitives + the BioHCC calibration construction for biomedical hidden-confounding benchmarks.

Probe measures what outcome-relevant hidden-confounding difficulty a benchmark contains and which mechanism-aware comparison that difficulty can support (benefit / equivalence / failure / abstention). BioHCC is a tunable, self-generating PK-PD construction with an exact (quadrature) interventional residual, for calibrating Probe under known causal regimes.

Scope. This is a measurement instrument, not an algorithm-ranking oracle. It reports which comparison a benchmark can support; it does not predict unseen-method or external-cohort performance. BioHCC generates its own synthetic data — the package ships and downloads no external or clinical data (MIMIC / eICU / PhysioNet must be obtained by the user under their own terms and are out of scope here).

Install

pip install biohcc                 # core: numpy only

Quickstart — measure a benchmark residual

import numpy as np
from biohcc import interventional_residual, residual_factorisation, gap_to_fit

# For a frozen (context, action), tabulate over latent draws u:
outcome           = ...  # phi(context, u)              shape (contexts, latent_draws)
action_likelihood = ...  # pi(target_action | context, u)
belief            = ...  # p(u | learner filtration)    (prior for memoryless; belief for persistent)

res = interventional_residual(outcome, action_likelihood, belief)
res["delta"]           # observation-to-intervention residual Delta*
fac = residual_factorisation(outcome, res["likelihood_ratio"], belief)
fac["g_mean"], fac["rho_squared_mean"], fac["chi_squared_mean"]   # g = alignment x assignment info

Quickstart — the BioHCC construction

from biohcc import memoryless_config, persistent_config, certify, certify_report, rollout

res = certify(memoryless_config(kappa_h=1.5, sigma_a=0.55))   # structured result, no printing
res.g, res.dstar, res.invariants_pass, res.certified, res.max_share

certify_report(persistent_config())        # prints the report incl. the prior-vs-belief (R7) trap
O, A, Y = rollout(500, memoryless_config(), seed=0)           # generate a cohort in memory

Map measurements to a decision

design_decision (pre-comparison) and outcome_class (post-comparison) implement the main-text Table I decision map; consequence_class is a thin convenience wrapper over the two. All are pure functions of explicit inputs — no universal threshold is inferred; the caller decides, per construction, what counts as "residual present", "supported", "resolvable" (D_Gamma), etc.

from biohcc import consequence_class

consequence_class(
    residual_present=True, estimand_aligned=True, baseline_recoverable=False,
    correction_channel_available=True, supported=True, resolvable=True,
    recovery_lower_bound=0.4, attribution_lower_bound=0.4, equivalence_margin=0.1,
).label          # -> "benefit"
# Table I precedence: any failed gate (support, applicability, resolvability D_Gamma,
# estimand, provenance) -> "abstention"; a certified structural zero whose registered
# interval lies inside the margin -> "equivalence"; an authorized benefit test not met
# -> "not-confirmed" (or "mechanism-contradicted" if a directional implication reverses).

Command line

biohcc certify  --variant both          # measure BioHCC-M and BioHCC-P certificates
biohcc generate --variant M --n-pat 500 --out cohort.npz
biohcc selftest                         # exact-invariant / identity checks (exit 0/1)
biohcc version

What Probe measures

• interventional residual Delta* = E_obs[Y|x,a] - E_do[Y|x,a] = Cov_p(w, f) — the discrepancy a correction must remove (zero if the latent does not change the outcome-relevant belief);
• factorisation g = rho^2 · chi2 — outcome alignment × assignment information;
• gap-to-fit Q / (Q + E_fit) — an evaluation-design-dependent power coordinate (not a ceiling);
• plus baseline accessibility, correction-channel availability, support and discriminability, which the caller supplies to consequence_class.

Exact invariants (E_p[w]=1, Delta*=Cov_p(w,f), Cauchy–Schwarz) are checked at run time; a violation means the probe or the simulator is wrong, not that a threshold was crossed.

Citation / provenance

Source repository: https://github.com/anonymous-rl-lab/biohcc. Frozen Zenodo release: https://doi.org/10.5281/zenodo.21621354. Preregistration and confirmatory records: https://osf.io/w62fd. See CHANGELOG.md. License: MIT.