Python API Reference

Risk Bridge exports a clean, strongly-typed public API from the root risk_bridge module.

import risk_bridge as rb

---

Configuration Dataclasses

UserDataSchema

Defines the mapping between input DataFrame column names and Risk Bridge concepts:

from risk_bridge import UserDataSchema

schema = UserDataSchema(
    x_cols=("X1", "X2", "X3", "X4"),
    y_col="caseY",               # default: "caseY"
    z_origin_col="zOrigin",       # default: "zOrigin"
    z_cat_col="zCat",             # default: "zCat"
    z_bins=(0.25, 0.5, 0.75),    # optional cutpoints
    allow_z_origin_from_zcat=False,
)

UserDataRunConfig

Encapsulates all options for an applied user-data run:

from risk_bridge import UserDataRunConfig

config = UserDataRunConfig(
    target_df=target_pl_df,
    source_df=source_pl_df,
    reference_df=reference_pl_df,
    schema=schema,
    sample_size=500,
    nsim=1,
    target_fpr=0.10,
    calibration_tolerance=0.02,
    output_root="data",
    run_label="my_cohort",
    n_jobs=1,
    path_jobs=1,
    write_parquet=False,
)

RunConfig & SimulationConfig

Typed container for simulated scenario experiments:

from risk_bridge import RunConfig, SimulationConfig, Scenario1PipelineOptions

---

Configuration Builders

Convenience functions for constructing scenario configurations:

build_scenario1_run_config

from risk_bridge import build_scenario1_run_config

cfg = build_scenario1_run_config(
    seed=42,
    nsim=10,
    n_target=10000,
    n_source=5000,
    n_reference=10000,
    sample_size=1000,
    target_fpr=0.10,
    output_root="data",
    run_label="scenario1",
)

build_scenario2_run_config

from risk_bridge import build_scenario2_run_config

cfg = build_scenario2_run_config(...)

build_scenario3_run_config

from risk_bridge import build_scenario3_run_config

cfg = build_scenario3_run_config(...)

---

Execution Functions

run_user_data(config: UserDataRunConfig) -> pathlib.Path

Executes risk bridging on user-provided cohorts, writes intermediate and final outputs, and returns the output directory path.

from risk_bridge import run_user_data

run_dir = run_user_data(config)
print(f"Artifacts written to: {run_dir}")

run_simulation(config: RunConfig, options: Scenario1PipelineOptions | None = None) -> pathlib.Path

Executes simulated pipeline runs and returns the resulting directory path.

from risk_bridge import run_simulation

run_dir = run_simulation(cfg)

run_summary(config: RunConfig) -> polars.DataFrame

Compact development helper that runs iterations in memory and returns a Polars DataFrame with one summary row per iteration.

---

Core Result Objects

The pipeline constructs frozen dataclasses to represent fitted models and evaluations:

FitResult

class FitResult:
    theta: np.ndarray          # [alpha, beta_x..., beta_z, gamma0, gamma_x..., sigma]
    success: bool              # True if optimizer succeeded and constraints met
    status: str                # Solver message
    n_iter: int                # Number of solver iterations
    objective: float           # Final negative log-likelihood value
    max_violation: float       # Maximum calibration constraint violation

EvaluationSummary

class EvaluationSummary:
    auc: float                 # Area under the ROC curve
    threshold: float           # Probability threshold at target FPR
    tpr: float                 # True positive rate (sensitivity)
    ppv: float                 # Positive predictive value (precision)
    tnr: float                 # True negative rate (specificity)

IterationMetrics

Groups evaluation summaries for ML and cMLE fits across both PSM and RS paths.