gen_surv

gen_surv is a Python library for simulating survival data and producing visualizations under a wide range of statistical models. Inspired by the R package genSurv, it offers a unified interface for generating realistic datasets for research, teaching and benchmarking.

Features

• Cox proportional hazards model (CPHM)
• Accelerated failure time models (log-normal, log-logistic, Weibull)
• Continuous-time multi-state Markov model (CMM)
• Time-dependent covariate model (TDCM)
• Time-homogeneous hidden Markov model (THMM)
• Mixture cure and piecewise exponential models
• Competing risks generators (constant and Weibull hazards)
• Visualization helpers built on matplotlib and lifelines
• Scikit-learn compatible data generator
• Conversion utilities for scikit-survival
• Command-line interface for dataset creation and visualization

Installation

Requires Python 3.11 or later (tested on 3.11, 3.12 and 3.13).

Install the latest release from PyPI:

pip install gen-surv

gen_surv installs matplotlib and lifelines for visualization. Support for scikit-survival is optional; install it to enable integration with the scikit-survival ecosystem or to run the full test suite:

pip install scikit-survival

To develop locally with all extras:

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

On Debian/Ubuntu you may need build-essential gfortran libopenblas-dev to build scikit-survival.

Development

Before committing changes, install the pre-commit hooks and run the tests:

pre-commit install
pre-commit run --all-files
pytest

Tests that depend on optional packages such as scikit-survival are skipped automatically when those packages are missing.

Usage

Python API

from gen_surv import generate, export_dataset, to_sksurv
from gen_surv.visualization import plot_survival_curve

sim = generate(
    model="cphm",
    n=100,
    beta=0.5,
    covariate_range=2.0,
    model_cens="uniform",
    cens_par=1.0,
)

plot_survival_curve(sim)
export_dataset(sim, "survival_data.rds")

# convert for scikit-survival
sks_dataset = to_sksurv(sim)

See the usage guide for more examples.

Command Line

Generate datasets and plots without writing Python code:

python -m gen_surv dataset cphm --n 1000 -o survival.csv

python -m gen_surv visualize survival.csv --output survival_plot.png

visualize accepts custom column names via --time-col and --status-col and can stratify by group with --group-col.

Supported Models

More details on each algorithm are available in the Algorithms page. For additional background, see the theory guide.

Documentation

Full documentation is hosted on Read the Docs. It includes installation instructions, tutorials, API references and a bibliography.

To build the docs locally:

cd docs
make html

Open build/html/index.html in your browser to view the result.

License

This project is licensed under the MIT License. See LICENSE for details.

Citation

If you use gen_surv in your research, please cite the project using the metadata in CITATION.cff.

Author

Diogo Ribeiro — ESMAD - Instituto Politécnico do Porto

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