Skip to content

Risk Bridge

Documentation CI PyPI version License: Apache-2.0

Risk Bridge is a Python package for estimating transportable binary-risk prediction models when the available cohorts do not share the same covariate support or when observational data is subject to selection bias and calibration drift.

The core methodology combines propensity-score matching (PSM), reference-cohort calibration, joint likelihood formulation, and constrained maximum likelihood estimation (cMLE) to deliver well-calibrated, transportable risk scores.

📖 Documentation Site: https://saehwanpark.github.io/risk-bridge/

The Problem: Risk Model Transportability

In healthcare and epidemiology, predictive models developed in one setting (the source population) often suffer from severe miscalibration when deployed in another setting (the target population). This calibration degradation arises from multiple sources:

  1. Covariate Shift: The distribution of baseline predictors \(P(X)\) differs between populations.
  2. Missing Risk Markers: High-dimensional, invasive, or expensive intermediate risk markers \(Z\) (e.g., specialized imaging, genetic sequencing, pathology markers) may be available in the source study but completely absent in the target registry.
  3. Selection Bias: Source cohorts derived from electronic health records (EHR) often reflect non-random sampling, disease-enriched referrals, or selective testing.

Standard unconstrained Maximum Likelihood Estimation (MLE) fitted on source data can lead to systematically biased risk estimates when applied across population boundaries.

Target Cohort (Evaluation Population)
  Covariates X observed, binary outcome Y evaluated.
        ⬇️
Source Cohort (Model Fitting Population)
  Rich data with baseline covariates X, binary outcome Y,
  and continuous/categorical intermediate markers Z. Subject to selection drift.
        ⬇️
Reference Cohort (Calibration Baseline)
  Representative population study providing external prevalence benchmarks
  P*(Y=1 | X ∈ S_k) across risk intervals S_k.

The Solution: Constrained Maximum Likelihood Estimation (cMLE)

Risk Bridge addresses transportability by formulating an optimization problem that balances goodness-of-fit on the source data with calibration constraints anchored by a representative external reference cohort:

  1. Base Risk Stratification: A baseline risk model \(\phi(X) = P(Y=1 \mid X)\) is estimated on the reference cohort to define risk intervals \(\mathcal{S}_1, \dots, \mathcal{S}_K\).
  2. Joint Likelihood Formulation: A joint model for \((Y, Z) \mid X\) is established on the source cohort, modeling \(Y \mid X, Z_{\text{cat}}\) via logistic regression and \(Z \mid X\) via a truncated-lognormal distribution.
  3. Calibration Constraint Enforcement: Parameter estimates \(\theta\) are constrained such that the model-implied event rates match the reference population benchmarks within an explicit tolerance \(\epsilon\):
\[ \lvert g_k(\theta) \rvert \le \epsilon, \quad k = 1, \dots, K \]
  1. Hierarchical Solver Ladder: Optimization utilizes a robust solver ladder: warm-starting from unconstrained BFGS, proceeding to interior-point constrained optimization (trust-constr) with analytic gradients and Jacobians, and falling back to Sequential Least Squares Programming (SLSQP) when necessary.

Key Highlights

  • Simulated & Applied Workflows: Out-of-the-box Monte Carlo simulations (Scenarios 1–3) for methodological benchmarking, and a robust pipeline for user-provided CSV cohorts.
  • Dual Analysis Paths: Evaluates Propensity Score Matched (PSM) source samples alongside Random Sampling (RS) baselines.
  • Analytic Derivatives: Exact closed-form gradients for negative log-likelihoods and constraint Jacobians for fast, reliable numerical convergence.
  • Standardized CSV Contract: Strict, versioned schema contract (schema_version=1.1.0) with complete run metadata, parameter estimates, and environment capture (environment.json).
  • Calibration Diagnostics: Comprehensive evaluation metrics including Calibration-in-the-Large (CITL), calibration slope, observed-to-expected (O/E) ratio, Brier score, and post-fit moment residuals.

Foundation Papers

  • Cao, Y., Ma, W., Zhao, G., McCarthy, A. M., & Chen, J. (2024). A constrained maximum likelihood approach to developing well-calibrated models for predicting binary outcomes. Lifetime Data Analysis, 30(3), 624–648.
  • Wang, L., & Chen, J. (2026). Developing Accurate Risk Prediction Using Biased Electronic Health Record Data. Manuscript in preparation.

Quickstart in 30 Seconds

Installation

uv add risk-bridge
# or with pip:
pip install risk-bridge

Run a Smoke Simulation

uv run risk-bridge \
  --mode simulated \
  --scenario 1 \
  --nsim 2 \
  --n-target 1000 \
  --n-source 500 \
  --n-reference 1000 \
  --sample-size 100 \
  --output-root data \
  --run-label smoke

Python API

from risk_bridge import build_scenario1_run_config, run_simulation

config = build_scenario1_run_config(
    nsim=2,
    n_target=1000,
    n_source=500,
    n_reference=1000,
    sample_size=100,
    output_root="data",
)
run_dir = run_simulation(config)
print(f"Results written to: {run_dir}")

For more in-depth tutorials, see Getting Started and the User Guide.