Skip to content

Quickstart Tutorial

This tutorial gets you up and running with Risk Bridge in about five minutes. You will run a small synthetic simulation, examine the output artifacts, and execute the equivalent pipeline in Python.

Step 1: Install Risk Bridge

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

Step 2: Run a Simulated Workflow from the CLI

Run a small simulation using the built-in Scenario 1 generator:

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

Explanation of Arguments:

  • --mode simulated: Use the synthetic data generator.
  • --scenario 1: Select built-in Scenario 1 data generating process.
  • --nsim 2: Run 2 Monte Carlo iterations.
  • --n-target, --n-source, --n-reference: Cohort sizes generated for each iteration.
  • --sample-size 100: Size of the subsamples drawn from source and target cohorts.
  • --output-root data: Directory where timestamped outputs will be written.
  • --run-label smoke_quickstart: Custom label appended to the output folder.

Step 3: Inspect the Generated Outputs

When the run completes, the CLI outputs the directory path where results are stored:

data/<timestamp>_smoke_quickstart/
├── intermediate/
│   ├── pe_by_iter.csv
│   ├── sample_psm_by_iter.csv
│   ├── sample_rs_by_iter.csv
│   └── xind_by_iter.csv
└── final/
    ├── accuracy_metrics.csv
    ├── calibration_metrics.csv
    ├── calibration_residuals.csv
    ├── est_cml_psm.csv
    ├── est_ml_psm.csv
    ├── fit_diagnostics.csv
    ├── roc_metrics.csv
    └── run_metadata.csv

Key Output Files to Check:

  1. final/fit_diagnostics.csv: Shows whether the cMLE solver converged successfully and reports the maximum constraint violation.
  2. final/calibration_metrics.csv: Reports Calibration-in-the-Large (CITL), calibration slope, observed/expected ratio, and Brier score.
  3. final/est_cml_psm.csv: Contains fitted parameters (\(\alpha, \beta_X, \beta_Z, \gamma_0, \gamma_X, \sigma\)) for the constrained MLE model.
  4. final/roc_metrics.csv: Area under the ROC curve (AUC) across iterations.

Step 4: Run from Python

You can execute the exact same pipeline programmatically using typed configurations:

from pathlib import Path
from risk_bridge import build_scenario1_run_config, run_simulation

# 1. Build a typed simulation configuration
config = build_scenario1_run_config(
    seed=42,
    nsim=2,
    n_target=1000,
    n_source=500,
    n_reference=1000,
    sample_size=100,
    output_root="data",
    run_label="python_quickstart",
)

# 2. Run the simulation
output_dir: Path = run_simulation(config)
print(f"Artifacts successfully saved to: {output_dir}")

# 3. Read back final results using Polars
import polars as pl

diagnostics = pl.read_csv(output_dir / "final" / "fit_diagnostics.csv")
print("Fit Diagnostics:")
print(diagnostics)

calib_metrics = pl.read_csv(output_dir / "final" / "calibration_metrics.csv")
print("Calibration Metrics:")
print(calib_metrics)

Next Steps