Skip to main content
surpyval logo

SurPyval - Survival Analysis in Python

actions PyPI version Python Version Documentation Status DOI

SurPyval is a Python package for survival analysis: the statistics of how long it takes for an event to happen. The event can be the failure of a bearing, the relapse or death of a patient, the default of a loan or the end of a customer's subscription, and the "time" can be hours, cycles, kilometres or weeks. It is for anyone with time-to-event data: engineers, clinicians and medical statisticians, economists and data scientists alike.

So why another survival analysis package? The intent was to mimic the scipy API as closely as possible, with a simple .fit() method for any type of distribution (parametric or non-parametric). SurPyval takes an arbitrary combination of observed, censored and truncated data. And it offers several parametric estimation methods, so an analyst has another way to estimate the parameters when one method fails. The parametric methods available are Maximum Likelihood Estimation (MLE), Probability Plotting (MPP), Mean Square Error (MSE), Method of Moments (MOM), and Maximum Product of Spacing (MPS). SurPyval can, for each type of estimator, take the following types of input data:

Method Para/Non-Para Observed Censored Truncated
MLE Parametric Yes Yes Yes
MPP Parametric Yes Yes Limited
MSE Parametric Yes Yes Limited
MOM Parametric Yes No No
MPS Parametric Yes Yes No
Kaplan-Meier Non-Parametric Yes Right only Left only
Nelson-Aalen Non-Parametric Yes Right only Left only
Fleming-Harrington Non-Parametric Yes Right only Left only
Turnbull (EM, or EM-ICM without truncation) Non-Parametric Yes Yes Yes

SurPyval also offers many different distributions for users, and because of the flexible implementation adding new distributions is easy. Further, the power of SurPyval lay in the robust parameter estimation, as such, some distributions, those that are supported on the half real line, can be offset to make a three- or four-parameter version. The currently available distributions are:

Distribution Offsetable
Weibull Yes
Normal No
LogNormal Yes
Gamma Yes
Beta No
Beta (4 parameter) No
Uniform No
Exponential Yes
Exponentiated Weibull Yes
Rayleigh Yes
Gumbel (and GumbelLEV) No
Logistic No
LogLogistic Yes

Discrete distributions: Poisson, Geometric, NegativeBinomial, DiscreteWeibull, BetaGeometric, Bernoulli and Binomial (with a number of trials per row); any continuous distribution can be discretised with Discretize. Any of them can be combined in a MixtureModel (with standard errors and Wald bounds), and custom distributions are supported.

This project grew out of a reliability engineering project, where parameters have long been estimated from a probability plot. SurPyval continues that tradition: any parametric distribution can have its estimate plotted on a probability plot, which gives an analyst in any field a sense of how well the parametric distribution fits against the non-parametric estimate. Alongside the tools an engineer expects (probability plots, offsets, B-lives, accelerated life tests, repairable systems, degradation) are those of biostatistics and econometrics (Kaplan-Meier, Cox regression, competing risks, frailty, predictive metrics).

Different fields name the same ideas differently: a failure is an event, a unit is a subject, reliability is survival and a suspension is a right censored observation. The API has one name for each (c for the censoring flag, sf for the survival function), and the documentation's glossary maps the vocabularies to each other.

The Model Landscape

SurPyval's models can be placed on a set of orthogonal axes. The table below cross-tabulates four of those axes — the time scale (continuous-time durations vs discrete-time trials), event recurrence, competing events, and covariates — against the estimation axis, and fills each cell with what can be used to implement it. The discrete-time models are single-event, not recurrent: Bernoulli is a single trial and Binomial is the sum of n such trials — neither is a recurrent-event process. A — marks a combination that is either not applicable (e.g. semiparametric estimation requires covariates) or not yet built.

Time Recurrence Events Covariates Parametric Semi-/Nonparametric
Continuous time Single event Single Without Weibull, Exponential, LogNormal, Gamma, … KaplanMeier, NelsonAalen, FlemingHarrington, Turnbull
Continuous time Single event Single With WeibullPH, WeibullAFT, WeibullPO, WeibullAH (every distribution), AcceleratedLife with surpyval.life_models, RoystonParmar, WeibullFrailty CoxPH, ProportionalOdds, AdditiveHazards, BuckleyJames, CoxFrailty, CoxMixedEffects; survival trees and forests (surpyval.ml)
Continuous time Single event Competing Without ParametricCompetingRisks CompetingRisks (CIF, with confidence bounds)
Continuous time Single event Competing With ParametricCompetingRisksRegression (a parametric regression per cause) FineGray, CompetingRisksProportionalHazards (with standard errors and summary())
Continuous time Recurrent Single Without HPP; NHPP: CrowAMSAA (with growth projection), Duane, CoxLewis; renewal, with each unit's next failure: GeneralizedRenewal, GeneralizedOneRenewal, ARA, ARI NonParametricCounting (MCF)
Continuous time Recurrent Single With ProportionalIntensityHPP, ProportionalIntensityNHPP —
Continuous time Recurrent Competing Without CauseSpecificNHPP CauseSpecificMCF
Continuous time Recurrent Competing With CauseSpecificProportionalIntensity (each failure mode its own baseline and coefficients) —
Discrete time Single event Single Without Bernoulli (single trial), Binomial (n trials, or a number per row) —
Discrete time Single event Single With use logistic / binomial regression (out of scope for this package) —

Beyond these axes: the dependence between two lifetimes with copulas (surpyval.multivariate: Gaussian, Student-t, Clayton, Frank, Gumbel, Joe and AMH, with rotations, standard errors and confidence bounds), degradation and remaining useful life (DegradationAnalysis, WienerProcess, GammaProcess, DestructiveDegradation; the Wiener and gamma processes with standard errors, bounds and AIC), and surpyval.forecast, the expected failures of units in service with prediction intervals, from a univariate, regression or repairable-system model. The parametric regression models have qf, cs and quantile_cb, with Wald, likelihood-ratio and bootstrap bounds, and the semi-parametric and frailty regressions have qf. An offset model's bounds can be bootstrapped (method="bootstrap") to take in the offset's uncertainty. Units that move between several states (healthy, ill, dead; working, degraded, failed) have multi-state models (surpyval.multistate): Aalen-Johansen transition and state occupation probabilities (MultiState) and a Cox model of each transition (MultiStateProportionalHazards), with standard errors and bounds.

Install and Quick Intro

SurPyval can be installed via pip using the PyPI repository

pip install surpyval

If you're familiar with survival analysis, and Weibull plotting, the following is a quick start. If you are new to the subject, start with Survival Analysis from Scratch in the documentation.

from surpyval import Weibull
from surpyval.datasets import load_bofors_steel

# Fetch some data that comes with SurPyval
data = load_bofors_steel()

x = data['x']
n = data['n']

model = Weibull.fit(x=x, n=n, offset=True)
model.plot();

Weibull Data and Distribution

Documentation

SurPyval is well documented, and improving, at the main documentation.

Design Principles

Every model in SurPyval keeps the same rules, so what you learn about one holds for the others:

  • Inputs. One data format everywhere (x, c, n, t, tl, tr). Invalid input raises a ValueError that says how to fix it. Missing values go nan in, nan out. Row order, time units and counts-versus-repeated-rows never change an answer.
  • Outputs. Results keep the shape of the query. The functions of a model agree with each other (sf + ff = 1, Hf = -log(sf), ...). Probabilities stay in [0, 1] and are monotone in time. Behaviour outside the data is defined and documented.
  • Estimation. A fit returns the optimum it claims, or says it could not. Every way of fitting a model (fit, fit_from_df, formulas) gives the same answer. Defaults are the statistically best standard choice and the same everywhere. Conventions follow R's survival and the other established references.
  • Uncertainty. Intervals achieve their stated coverage and behave consistently across confidence levels and one- or two-sided bounds.
  • Behaviour. One seed rule. Every model round-trips through JSON. Names and defaults are consistent across families. Defaults stay simple; a method for harder cases is added as an option, not a replacement. Warnings are useful and never raw numpy noise. Every public item has a runnable example.

Each principle is enforced by tests, most as properties checked against every registered model. The Design Principles page lists them in full, with the tests that check each one and the open issues where a model does not yet comply.

Development

Issues

Questions, bug reports and suggestions are welcome as GitHub issues.

Dependencies

pip install -r requirements_dev.txt

Testing

Run the testing suite by simply executing:

pytest

or use coverage to get a coverage report:

coverage run -m pytest  # Run pytest under coverage's watch
coverage report         # Print coverage report
coverage html           # Make a html coverage report (really useful), open htmlcov/index.html

Pre-commit

  • Pip install pre-commit (it's in requirements_dev.txt anyways)
  • Run pre-commit install which sets up the git hook scripts
  • If you'd like, run pre-commit run --all-files to run the hooks on all files
  • When you go to commit, it will only proceed after all the hooks succeed

Related

Reliafy is a hosted, browser-based app built on SurPyval, for fitting life distributions, regression and recurrent-event models to censored data without writing code.

Contact

Email derryn if you want any features or to see how SurPyval can be used for you.

Metadata

Release files for surpyval 0.27

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for surpyval 0.27
File Size Uploaded Provenance Actions
surpyval-0.27.tar.gz 6.6 MB With provenance Details for surpyval-0.27.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for surpyval 0.27
File Interpreter ABI Platform Actions
surpyval-0.27-py3-none-any.whl Python 3 none any Details for surpyval-0.27-py3-none-any.whl

Total release size: 14.0 MB

Release files / surpyval-0.27.tar.gz

Download URL surpyval-0.27.tar.gz
Size 6.6 MB
Tags Source
SHA-256 checksum
How to use checksums
e001c189a1d8216101f84f6af7f09c92ac1d8380b67a8e95fa405c46a4274aa6
BLAKE2b-256 checksum
How to use checksums
f285bcda675346bcce27ec6802e24e4473d55a770d5bc8f3336ea0b47d11cb0b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Release files / surpyval-0.27-py3-none-any.whl

Download URL surpyval-0.27-py3-none-any.whl
Size 7.4 MB
Tags Python 3
SHA-256 checksum
How to use checksums
6d6243e82f5628ece5371566e3647a5af4218a41821dbc6f96b61ce834221ef4
BLAKE2b-256 checksum
How to use checksums
1efa4baf3b4d965e65db6776d480215d17f59b3a42028ead72dbf4ee1e97c56c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Security for surpyval 0.27

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for surpyval-0.27.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.27 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page