Metadata-Version: 2.4
Name: biohcc
Version: 0.5.0
Summary: Probe measurement primitives and the BioHCC calibration construction for biomedical hidden-confounding benchmarks
Author: BioHCC / Probe authors
License-Expression: MIT
Project-URL: Homepage, https://github.com/anonymous-rl-lab/biohcc
Project-URL: Source, https://github.com/anonymous-rl-lab/biohcc
Project-URL: Archive, https://doi.org/10.5281/zenodo.21621354
Project-URL: Preregistration, https://osf.io/w62fd
Keywords: causal-inference,hidden-confounding,benchmark,biomedical,treatment-effect,off-policy-evaluation,proximal,calibration
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# 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

```bash
pip install biohcc                 # core: numpy only
```

## Quickstart — measure a benchmark residual

```python
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

```python
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.

```python
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

```bash
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.
