CLI Reference

Risk Bridge provides a command-line interface via risk-bridge (or uv run risk-bridge).

General Syntax

risk-bridge --mode {simulated|user-data} [OPTIONS]

---

Simulated Mode (--mode simulated)

Runs Monte Carlo simulations under synthetic data-generating processes (Scenario 1, 2, or 3).

risk-bridge \
  --mode simulated \
  --scenario {1,2,3} \
  --nsim <int> \
  --n-target <int> \
  --n-source <int> \
  --n-reference <int> \
  --sample-size <int> \
  --target-fpr <float> \
  --calibration-tolerance <float> \
  --seed <int> \
  --n-jobs <int> \
  --path-jobs <int> \
  --output-root <path> \
  --run-label <string> \
  [--write-parquet]

Options

Option	Type	Default	Description
--scenario	int	1	Synthetic scenario (\(1\), \(2\), or \(3\)).
--nsim	int	10	Number of repeated Monte Carlo iterations.
--n-target	int	10000	Target population generation size.
--n-source	int	5000	Source population generation size.
--n-reference	int	10000	Reference population generation size.
--sample-size	int	1000	Sample size drawn for each iteration.
--target-fpr	float	0.10	False positive rate used to select risk threshold.
--calibration-tolerance	float	0.02	Calibration inequality tolerance (\(\epsilon\)).
--seed	int	42	Random number generator seed.
--n-jobs	int	1	Multiprocessing parallelism across iterations.
--path-jobs	int	1	Multithreading parallelism across sampling paths (PSM and RS).
--output-root	path	.	Root directory for output folder.
--run-label	str	sim	Label appended to timestamped output directory.
--write-parquet	flag	false	If set, writes parquet mirrors alongside CSVs.
--print-every	int	1	Progress logging interval.

---

User-Data Mode (--mode user-data)

Executes risk bridging on prepared CSV datasets.

risk-bridge \
  --mode user-data \
  --target-csv <path> \
  --source-csv <path> \
  --reference-csv <path> \
  --x-cols <col1,col2,...> \
  [--y-col <col>] \
  [--z-origin-col <col>] \
  [--z-cat-col <col>] \
  [--z-bins <b1,b2,...>] \
  [--allow-z-origin-from-zcat] \
  --sample-size <int> \
  [--nsim <int>] \
  [--target-fpr <float>] \
  [--calibration-tolerance <float>] \
  [--seed <int>] \
  [--n-jobs <int>] \
  [--path-jobs <int>] \
  [--output-root <path>] \
  [--run-label <string>] \
  [--write-parquet]

Options

Option	Type	Default	Description
--target-csv	path	required	Path to target population CSV.
--source-csv	path	required	Path to source population CSV.
--reference-csv	path	required	Path to reference population CSV.
--x-cols	str	required	Comma-separated list of discrete covariate columns.
--y-col	str	caseY	Name of binary outcome column.
--z-origin-col	str	zOrigin	Name of continuous risk marker column.
--z-cat-col	str	zCat	Name of categorical risk stratum column.
--z-bins	str	None	Comma-separated cutpoints for binning continuous \(Z\).
--allow-z-origin-from-zcat	flag	false	Derive continuous coordinates from category bins if continuous \(Z\) is absent.
--sample-size	int	required	Number of subjects sampled per analysis.
--nsim	int	1	Number of bootstrap/subsample iterations.
--output-root	path	.	Root directory for output folder.
--run-label	str	user	Folder label for this run.