Example Datasets & Walkthrough

The examples/ directory contains privacy-safe synthetic datasets and runnable Python scripts demonstrating how to bridge risk between disparate cohorts.

---

Bundled Example Datasets

The repository provides three pre-generated cohorts under examples/:

• examples/target.csv (\(N = 5{,}000\)): The target population where performance is evaluated.
• examples/source.csv (\(N = 2{,}000\)): The source population used for model fitting.
• examples/reference.csv (\(N = 5{,}000\)): The reference cohort providing external calibration benchmarks.

Data Schema

Each dataset contains:

Column	Type	Description
caseY	Integer	Binary outcome indicator (\(0\) = non-case, \(1\) = case)
X1	Integer	Discrete baseline covariate 1
X2	Integer	Discrete baseline covariate 2
X3	Integer	Discrete baseline covariate 3
X4	Integer	Discrete baseline covariate 4
zOrigin	Float	Continuous intermediate risk marker in \((0, 1]\)
zCat	Integer	Categorical risk stratum index in \(\{0, 1, 2, 3\}\)

These synthetic datasets exhibit realistic properties: 1. Covariate Shift: The joint distribution \(P(X)\) differs between the source and target populations. 2. Selection Bias: The source cohort has an enriched event rate (\(P(Y=1)\)) compared to the reference population. 3. Miscalibration: Models fit naively on the source cohort show systematic calibration intercept drift.

---

Runnable Example Scripts

1. Template for User-Data Workflows: examples/user_data_template.py

This script loads the three CSV files and runs the user-data pipeline using the high-level Python API:

from pathlib import Path
import polars as pl
from risk_bridge import UserDataRunConfig, UserDataSchema, run_user_data

REPO_ROOT = Path(__file__).resolve().parent

# 1. Load the cohorts
target_df = pl.read_csv(REPO_ROOT / "target.csv")
source_df = pl.read_csv(REPO_ROOT / "source.csv")
reference_df = pl.read_csv(REPO_ROOT / "reference.csv")

# 2. Define the schema mapping
schema = UserDataSchema(
    x_cols=("X1", "X2", "X3", "X4"),
    y_col="caseY",
    z_origin_col="zOrigin",
    z_cat_col="zCat",
)

# 3. Configure the run
config = UserDataRunConfig(
    target_df=target_df,
    source_df=source_df,
    reference_df=reference_df,
    schema=schema,
    sample_size=500,
    output_root=str(REPO_ROOT / "output"),
    run_label="user_data_example",
)

# 4. Execute estimation
out_dir = run_user_data(config)
print(f"Run completed. Results in: {out_dir}")

Run this script directly from the repository root:

uv run python examples/user_data_template.py

2. Simulated Pipeline Walkthrough: examples/simulated_quickstart.py

This script demonstrates Scenario 2 data generation and estimation:

uv run python examples/simulated_quickstart.py

It builds a typed RunConfig, executes run_simulation, and prints summary tables comparing ordinary ML with constrained cMLE.

---

Running with the CLI on Example Data

You can also run the user-data pipeline directly from the command line against the example CSVs:

uv run risk-bridge \
  --mode user-data \
  --target-csv examples/target.csv \
  --source-csv examples/source.csv \
  --reference-csv examples/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 example_run