gen_surv

Simulate survival data with a known truth.

gen_surv generates synthetic time-to-event datasets from twelve models — proportional hazards, accelerated failure time, competing risks, cure fractions, piecewise hazards, recurrent events and two illness-death processes — so you can test an estimator against parameters you chose yourself.

It is a Python port of the R package genSurv, extended well past the original's four models.

📖 Documentation · 🚀 Quickstart · 🧪 Choosing a model

Install

pip install gen-surv

Python 3.11, 3.12 and 3.13. Everything is included except scikit-survival, which is optional and needed only for the two conversion helpers:

pip install scikit-survival

The package ships py.typed, so mypy and pyright check your calls into it rather than treating it as untyped.

Thirty seconds

from gen_surv import generate

df = generate(
    model="cphm",           # Cox proportional hazards
    n=6,
    beta=0.5,               # log hazard ratio
    covariate_range=2.0,    # X0 ~ Uniform(0, 2)
    model_cens="uniform",
    cens_par=1.0,
    seed=42,
)
print(df)

       time  status        X0
0  0.438878     0.0  1.547912
1  0.094177     0.0  1.394736
2  0.037041     1.0  1.522279
3  0.370798     0.0  0.900772
4  0.646901     1.0  1.287730
5  0.251113     1.0  0.454477

You picked beta = 0.5, so you know what a correct estimator should recover:

from lifelines import CoxPHFitter

df = generate(model="cphm", n=5000, beta=0.5, covariate_range=2.0,
              model_cens="uniform", cens_par=1.0, seed=7)

CoxPHFitter().fit(df, duration_col="time", event_col="status").params_
# X0    0.501

That is the whole idea. Every column was produced by a mechanism you specified, so anything an estimator gets wrong is the estimator's fault.

The twelve models

Every model has a page covering its parameters, the mathematics, a worked example, and a check that the parameters can be recovered from the data it generates — start at Choosing a model.

The output shape is not the same for every model. Multi-state generators return several rows per subject, and column names differ between families. See Output schemas before writing code that consumes a generated frame.

A thirteenth, outside generate()

The twelve above each fix a state structure. When yours is not among them, gen_multistate takes the graph itself:

from gen_surv import ExponentialBaseline, Transition, WeibullBaseline, gen_multistate

multistate = gen_multistate(
    n=500,
    transitions=[
        Transition(1, 2, WeibullBaseline(shape=1.2, scale=3.0), [0.4]),  # fall ill
        Transition(2, 1, ExponentialBaseline(rate=0.6), [0.0]),          # recover
        Transition(2, 3, ExponentialBaseline(rate=0.2), [0.6]),          # die while ill
    ],
    clock="reset",
    seed=1,
)

Every edge carries its own baseline hazard and coefficients. A state with no outgoing edge is absorbing, and cycles are allowed - recovery above is a transition like any other. clock="forward" measures the hazard from entry to the study, giving a Markov process; clock="reset" restarts it at each state, giving a semi-Markov one.

cmm and thmm are configurations of this engine rather than separate implementations. It takes a list of objects rather than scalars, so it has no model= string and no command-line form - import it directly. See The multistate engine.

The ground truth, not just the data

A generated frame looks like a real one — which means it hides the same things. simulate() hands back what a real dataset never could:

from gen_surv import simulate

result = simulate("cphm", n=1000, beta=0.5, covariate_range=2.0,
                  model_cens="uniform", cens_par=1.0, seed=42)

result.data                      # the frame generate() would return
result.config                    # model, parameters, seed, gen_surv version
result.truth["event_time"]       # when each subject would have failed
result.truth["censoring_time"]   # what censoring hid

Several models draw their coefficients for you when you leave them out. result.truth["betas"] is the only way to learn what they were — without it those datasets cannot validate anything.

Any hazard shape

Every generator that draws a time inverts a cumulative hazard, so the shape is a parameter rather than a fork in the code:

from gen_surv import generate, LogLogisticBaseline

recurrent = generate(model="recurrent_events", n=500,
                     baseline=LogLogisticBaseline(shape=2.0, scale=1.5),
                     betas=[0.4, -0.2], followup_time=6.0, seed=1)

Exponential, Weibull, Gompertz, log-logistic and piecewise-constant are built in, and anything implementing hazard, cumulative_hazard and its inverse works too.

Beyond generating

from gen_surv import describe_survival, plot_survival_curve, export_dataset, to_sksurv

describe_survival(df)              # events, censoring, median follow-up
plot_survival_curve(df)            # Kaplan-Meier, optionally stratified
export_dataset(df, "data.rds")     # csv, json, feather or rds
to_sksurv(df)                      # structured array for scikit-survival

• Ground truth — configurations, latent times, the coefficients actually used
• Baseline hazards — the five families, and writing your own
• Censoring — the built-in mechanisms, hitting a target event rate, applying your own distribution
• Covariates — the three schemes across model families
• Summaries — event counts, quality checks, dataset comparison
• Plotting — survival curves, hazard comparisons, covariate effects
• Fitting models — lifelines, scikit-survival, scikit-learn, R

Command line

gen_surv dataset cphm --n 1000 --beta 0.5 --seed 42 -o survival.csv
gen_surv visualize survival.csv --group-col X0 --output km.png

Repeat a flag for list arguments — --beta 0.5 --beta -0.3. Every one of the twelve models is reachable from the command line. Full option reference in the CLI guide.

Reproducibility

Every generator takes a seed, accepting an int or a numpy.random.Generator. The same seed on the same version always gives the same frame, on any platform.

A bug fix in a sampler changes the draws a seed produces, so pin the version alongside the seed for anything that must reproduce:

gen-surv==3.1.2

See Reproducibility.

Documentation

https://diogoribeiro7.github.io/genSurvPy/

Built with Material for MkDocs and mkdocstrings, and rebuilt from the release tag by the Pages workflow — so it documents the version on PyPI, not unreleased work.

Development

git clone https://github.com/DiogoRibeiro7/genSurvPy.git
cd genSurvPy
poetry install --with dev

pre-commit install
pre-commit run --all-files     # black, isort, flake8, mypy
pytest                         # tests needing optional packages skip themselves

Docs:

poetry install --with docs
poetry run mkdocs serve        # live reload on http://127.0.0.1:8000

On Debian and Ubuntu, building scikit-survival may need build-essential gfortran libopenblas-dev.

Work happens on develop; main carries releases. See CONTRIBUTING.md.

Citation

@software{ribeiro_gensurv,
  title   = {gen_surv: Survival Data Simulation in Python},
  author  = {Diogo Ribeiro},
  url     = {https://github.com/DiogoRibeiro7/genSurvPy},
  version = {3.1.2}
}

Machine-readable metadata: CITATION.cff and .zenodo.json.

License

MIT — see LICENSE.

Author

Diogo Ribeiro — ESMAD, Instituto Politécnico do Porto

• ORCID: https://orcid.org/0009-0001-2022-7072
• Email: dfr@esmad.ipp.pt · diogo.debastos.ribeiro@gmail.com
• GitHub: @DiogoRibeiro7