Unified User Guide

This unified guide combines the conceptual foundation, data contract, CLI reference, and outputs into a single comprehensive manual.

---

1. Concepts

Risk Bridge addresses risk model transportability across three cohorts:

• target: The destination population where predictions are evaluated.
• source: The population where the model is fitted, containing baseline predictors \(X\) and rich intermediate marker \(Z\).
• reference: An external benchmark cohort used to calibrate the model.

---

2. Input Data Requirements

All input CSV files must share: - Binary outcome: caseY \(\in \{0, 1\}\). - Discrete feature columns passed via --x-cols. - Continuous marker: zOrigin in \((0, 1]\), or categorical marker: zCat in \(\{0, \dots, K\}\).

---

3. CLI Quick Reference

Simulated Run

uv run risk-bridge \
  --mode simulated \
  --scenario 1 \
  --nsim 5 \
  --n-target 5000 \
  --n-source 2000 \
  --n-reference 5000 \
  --sample-size 500 \
  --output-root data \
  --run-label sim_demo

User-Data Run

uv run risk-bridge \
  --mode user-data \
  --target-csv target.csv \
  --source-csv source.csv \
  --reference-csv reference.csv \
  --x-cols X1,X2,X3,X4 \
  --y-col caseY \
  --z-origin-col zOrigin \
  --z-cat-col zCat \
  --sample-size 500 \
  --nsim 1 \
  --output-root data \
  --run-label user_demo

---

4. Output Summary

Results are written under <output_root>/<timestamp>_<run_label>/final/:

• run_metadata.csv: Configuration parameters and schema version (1.1.0).
• fit_diagnostics.csv: Optimizer convergence, objective values, and constraint feasibility.
• est_cml_psm.csv: cMLE parameter estimates.
• est_ml_psm.csv: Ordinary MLE parameter estimates.
• calibration_metrics.csv: CITL, slope, O/E ratio, and Brier score.
• calibration_residuals.csv: Stratum-specific moment residuals.
• roc_metrics.csv: Target cohort AUC values.
• accuracy_metrics.csv: Target cohort classification metrics at target FPR.
• environment.json: Reproducibility metadata and numerical tolerance contract.