Skip to content

Command line

Installing the package puts a gen_surv command on your path. It has two subcommands.

gen_surv --help

 Usage: gen_surv [OPTIONS] COMMAND [ARGS]...

 Generate synthetic survival datasets.

+- Commands ------------------------------------------------------------------+
| dataset     Generate survival data and optionally save to CSV.              |
| visualize   Visualize survival data from a CSV file.                        |
+-----------------------------------------------------------------------------+

python -m gen_surv does the same thing, which is handy when the script directory is not on PATH.

dataset

gen_surv dataset MODEL [OPTIONS]

MODEL is any of the twelve names — cphm, cmm, tdcm, thmm, aft_ln, aft_weibull, aft_log_logistic, competing_risks, competing_risks_weibull, mixture_cure, piecewise_exponential, recurrent_events.

Writes CSV to the path given by -o, or to stdout when it is omitted:

# To a file
gen_surv dataset cphm --n 1000 --beta 0.5 --covariate-range 2.0 -o cphm.csv

# To stdout, so it pipes
gen_surv dataset aft_ln --n 500 --beta 0.5 --beta -0.3 --sigma 1.0 | head -5

Options

Option Default Applies to
--n 100 all models
--model-cens uniform all models
--cens-par 1.0 all models
--beta 0.5 all models — repeat the flag for several coefficients
--covariate-range, --covar 2.0 cphm, cmm, thmm
--sigma 1.0 aft_ln
--shape 1.5 aft_weibull, aft_log_logistic
--scale 2.0 aft_weibull, aft_log_logistic
--n-risks 2 competing risks
--baseline-hazards — competing_risks — repeat the flag
--shape-params, --scale-params — competing_risks_weibull — repeat
--cure-fraction, --baseline-hazard — mixture_cure
--breakpoints, --hazard-rates — piecewise_exponential — repeat
--rate — cmm (six values), thmm (three), recurrent_events (one) — repeat the flag
--dist weibull tdcm — weibull or exponential
--corr 0.5 tdcm — dependence between the covariate and the crossover
--dist-par — tdcm — four values for Weibull, two for exponential — repeat
--lam 1.0 tdcm — baseline hazard rate
--process ag recurrent_events — ag, pwp_tt or pwp_gt
--baseline exponential recurrent_events — exponential, weibull or gompertz
--stratum-effects — recurrent_events — per-event factors, repeat the flag
--max-events None recurrent_events — stop a subject after this many events
--followup-time 10.0 recurrent_events — administrative end of follow-up
--seed None all models
-o stdout output CSV path

Repeat the flag for list arguments

There is no comma syntax. Two coefficients means two --beta flags:

gen_surv dataset aft_weibull --n 200 --beta 0.5 --beta -0.3 \
    --shape 1.5 --scale 2.0 -o aft.csv

Same for --breakpoints, --hazard-rates, --baseline-hazards, --shape-params, --scale-params, --rate and --dist-par.

--rate carries a vector

cmm needs six values and thmm three, so --rate is a list. For recurrent_events, which wants a single number, the first value is used. Omit it and each model falls back to a documented default.

Examples

# Cox PH, seeded so it is reproducible
gen_surv dataset cphm --n 2000 --beta 0.5 --covariate-range 2.0 \
    --model-cens uniform --cens-par 1.0 --seed 42 -o cphm.csv

# Weibull AFT with two covariates
gen_surv dataset aft_weibull --n 1000 --beta 0.5 --beta -0.3 \
    --shape 1.5 --scale 2.0 --seed 42 -o aft.csv

# Competing risks with three causes
gen_surv dataset competing_risks --n 1000 --n-risks 3 \
    --baseline-hazards 0.3 --baseline-hazards 0.2 --baseline-hazards 0.1 \
    --seed 42 -o cr.csv

# Piecewise exponential, two intervals
gen_surv dataset piecewise_exponential --n 1000 \
    --breakpoints 1.0 --hazard-rates 0.5 --hazard-rates 1.0 \
    --seed 42 -o pw.csv

# Illness-death, counting-process form. cmm takes three coefficients and six
# rates: an intensity and a shape for each of 1->2, 1->3 and 2->3.
gen_surv dataset cmm --n 500 --beta 0.1 --beta 0.2 --beta 0.3 \
    --covariate-range 1.0 \
    --rate 0.1 --rate 1.0 --rate 0.2 --rate 1.0 --rate 0.1 --rate 1.0 \
    --seed 42 -o cmm.csv

# The same process as a state panel: three coefficients, three intensities
gen_surv dataset thmm --n 500 --beta 0.1 --beta 0.2 --beta 0.3 \
    --covariate-range 1.0 --rate 0.2 --rate 0.3 --rate 0.4 \
    --seed 42 -o thmm.csv

# A covariate that switches on partway through follow-up
gen_surv dataset tdcm --n 500 --beta 0.5 --beta 0.3 \
    --dist weibull --corr 0.5 --lam 1.0 --seed 42 -o tdcm.csv

--seed is worth typing every time

Without it, the same command gives different data on every run, and there is no way to get the first dataset back. See Reproducibility.

visualize

Reads a CSV and writes a Kaplan-Meier plot:

gen_surv visualize data.csv --output km.png
Option Default Meaning
--time-col time column with the observed times
--status-col status column with the event indicator
--group-col None column to stratify by
--output survival_plot.png image path 
# Stratified by a binary covariate
gen_surv visualize data.csv --group-col X0 --output stratified.png

# For a tdcm file, whose time column is called `stop`
gen_surv visualize tdcm.csv --time-col stop --output tdcm.png

Grouping on a continuous covariate produces one curve per distinct value, which is never what you want. Bin it first in Python — see Plotting.

Chaining the two

gen_surv dataset cphm --n 2000 --beta 0.8 --seed 1 -o cphm.csv \
  && gen_surv visualize cphm.csv --output cphm.png

What the CLI cannot do

  • Only CSV out. For Feather, JSON or RDS, use export_dataset in Python.
  • No per-covariate distribution control. --covariate-dist does not exist; use Python for covariate_dist and covariate_params.
  • No summaries. describe_survival and the gen_surv.summary functions are Python-only — see Summarising a dataset.
  • No ground truth. The coefficients a model drew for itself, latent event times and the tdcm crossover come only from simulate().