Data Preparation & Schemas¶

To run Risk Bridge on your own clinical or epidemiological data, prepare three CSV files conforming to the canonical data contract.

Canonical Column Specification¶

Risk Bridge maps input columns into four canonical concepts:

Canonical Name	Role	Expected Format / Range	Required In
`caseY`	Binary outcome	Integer \(\{0, 1\}\)	Target, Source, Reference
`X1, X2, ...`	Discrete baseline covariates	Integer category codes (e.g. \(0, 1, \dots\))	Target, Source, Reference
`zOrigin`	Continuous risk marker	Floating point \((0, 1]\)	Source
`zCat`	Categorical risk bin	Integer \(\{0, 1, \dots, K\}\)	Source

Covariate Support & Discretization¶

The statistical formulation of cMLE requires integrating over the conditional distribution of \(X\):

\[ P(Y = 1 \mid X \in \mathcal{S}_k) = \frac{\sum_{x \in \mathcal{S}_k} P(Y=1 \mid X=x) P(X=x)}{\sum_{x \in \mathcal{S}_k} P(X=x)} \]

Because summation occurs across the joint Cartesian support of \(X\), covariates \(X\) must be discrete or categorical.

[!IMPORTANT] Cartesian Cardinality Limit: If you have continuous predictors (such as age, BMI, or blood pressure), discretize them into clinically sensible bins (e.g., deciles or quintiles) before feeding them into Risk Bridge. The total number of unique Cartesian combinations \(\prod_j \lvert \mathcal{X}_j \rvert\) should ideally not exceed \(10{,}000\) to maintain fast numerical integration.

Handling the \(Z\) Risk Marker¶

The intermediate marker \(Z\) can be represented either continuously (zOrigin) or categorically (zCat):

Automatic Derivation of `zCat` via `--z-bins`¶

If your source data only provides continuous values zOrigin, pass --z-bins to automatically bin \(Z\):

uv run risk-bridge \
  --mode user-data \
  --target-csv target.csv \
  --source-csv source.csv \
  --reference-csv reference.csv \
  --x-cols Age_Cat,Sex,Stage \
  --z-origin-col z_score \
  --z-bins 0.25,0.50,0.75 \
  ...

Automatic Derivation of `zOrigin` from `zCat`¶

If your source data already contains categorical bins zCat and you want to approximate continuous coordinates, use --allow-z-origin-from-zcat. This will assign category midpoints automatically.

Validation Checks Performed by the Pipeline¶

Before model fitting begins, the preprocessing layer (risk_bridge.preprocess) automatically validates:

Binary Check: caseY contains only \(\{0, 1\}\).
Missingness: No missing (NaN / null) values in the specified columns.
Common Support: At least some overlap exists in the feature support between source and target cohorts.
Sample Size: --sample-size does not exceed the total rows available in either the target or source dataset.
Positive Cases: Both non-cases (\(0\)) and cases (\(1\)) must be present in every cohort.