Package auton_survival
The autonsurvival
Package
The python package autonsurvival
is repository of reusable utilities for projects
involving censored TimetoEvent Data. autonsurvival
provides a flexible APIs
allowing rapid experimentation including dataset preprocessing, regression,
counterfactual estimation, clustering and phenotyping and propensity adjusted evaluation.
For complete details on autonsurvival
see:
• White Paper • Documentation • Demo Notebooks
What is Survival Analysis?
Survival Analysis involves estimating when an event of interest, T would take places given some features or covariates X . In statistics and ML these scenarious are modelled as regression to estimate the conditional survival distribution, P(T>tX) . As compared to typical regression problems, Survival Analysis differs in two major ways:
 The Event distribution, T has positive support, T \in [0, \infty) .
 There is presence of censoring (ie. a large number of instances of data are lost to follow up.)
Figure 1. Illustration of Censoring
The Auton Survival Package
The package auton_survival
is repository of reusable utilities for projects
involving censored TimetoEvent Data. auton_survival
allows rapid
experimentation including dataset preprocessing, regression, counterfactual
estimation, clustering and phenotyping and propensityadjusted evaluation.
Survival Regression
auton_survival.models
Currently supported Survival Models include:
Training a Deep Cox Proportional Hazards Model with autonsurvival
:
from auton_survival import datasets, preprocessing, models
# Load the SUPPORT Dataset
outcomes, features = datasets.load_dataset("SUPPORT")
# Preprocess (Impute and Scale) the features
features = preprocessing.Preprocessor().fit_transform(features)
# Train a Deep Cox Proportional Hazards (DCPH) model
model = models.cph.DeepCoxPH(layers=[100])
model.fit(features, outcomes.time, outcomes.event)
# Predict risk at specific time horizons.
predictions = model.predict_risk(features, t=[8, 12, 16])
Figure 2. Violation of the Proportional Hazards Assumption
auton_survival.estimators
[Demo Notebook]
This module provides a wrapper SurvivalModel
to model
survival datasets with standard survival (timetoevent) analysis methods.
The use of the wrapper allows a simple standard interface for multiple different
survival regression methods.
auton_survival.estimators
also provides convenient wrappers around other popular
python survival analysis packages to experiment with Random Survival Forests and
Weibull Accelerated Failure Time regression models.
from auton_survival import estimators
# Train a Deep Survival Machines model using the SurvivalModel class.
model = estimators.SurvivalModel(model='dsm')
model.fit(features, outcomes)
# Predict risk at time horizons.
predictions = model.predict_risk(features, times=[8, 12, 16])
auton_survival.experiments
[Demo Notebook]
Modules to perform standard survival analysis experiments. This module
provides a toplevel interface to run auton_survival
style experiments
of survival analysis, involving options for crossvalidation and
nested crossvalidation style experiments with multiple different survival
analysis models.
The module supports multiple model peroformance evaluation metrics and further eases evaluation by automatically computing the censoring adjusted estimates, such as Time Dependent Concordance Index and Brier Score with IPCW adjustment.
# auton_survival crossvalidation experiment.
from auton_survival.datasets import load_dataset
outcomes, features = load_dataset(dataset='SUPPORT')
cat_feats = ['sex', 'income', 'race']
num_feats = ['age', 'resp', 'glucose']
from auton_survival.experiments import SurvivalRegressionCV
# Instantiate an auton_survival Experiment
experiment = SurvivalRegressionCV(model='cph', num_folds=5,
hyperparam_grid=hyperparam_grid)
# Fit the `experiment` object with the specified Cox model.
model = experiment.fit(features, outcomes, metric='ibs',
cat_feats=cat_feats, num_feats=num_feats)
Phenotyping And Knowledge Discovery
auton_survival.phenotyping
[Demo Notebook]
auton_survival.phenotyping
allows extraction of latent clusters or subgroups
of patients that demonstrate similar outcomes. In the context of this package,
we refer to this task as phenotyping. auton_survival.phenotyping
provides
the following phenotyping utilities:
 Intersectional Phenotyping: Recovers groups, or phenotypes, of individuals over exhaustive combinations of userspecified categorical and numerical features.
from auton_survival.phenotyping import IntersectionalPhenotyper
# ’ca’ is cancer status. ’age’ is binned into two quantiles.
phenotyper = IntersectionalPhenotyper(num_vars_quantiles=(0, .5, 1.0),
cat_vars=['ca'], num_vars=['age'])
phenotypes = phenotyper.fit_predict(features)
 Unsupervised Phenotyping: Identifies groups of individuals based on structured similarity in the fature space by first performing dimensionality reduction of the input covariates, followed by clustering. The estimated probability of an individual to belong to a latent group is computed as the distance to the cluster normalized by the sum of distance to other clusters.
from auton_survival.phenotyping import ClusteringPhenotyper
# Dimensionality reduction using Principal Component Analysis (PCA) to 8 dimensions.
dim_red_method, = 'pca',
# We use a Gaussian Mixture Model (GMM) with 3 components and diagonal covariance.
clustering_method, n_clusters = 'gmm',
# Initialize the phenotyper with the above hyperparameters.
phenotyper = ClusteringPhenotyper(clustering_method=clustering_method,
dim_red_method=dim_red_method,
n_components=n_components,
n_clusters=n_clusters)
# Fit and infer the phenogroups.
phenotypes = phenotyper.fit_predict(features)
 Supervised Phenotyping: Identifies latent groups of individuals with similar
survival outcomes. This approach can be performed as a direct consequence of training
the
Deep Survival Machines
andDeep Cox Mixtures
latent variable survival regression estimators using thepredict latent z
method.
from auton_survival.models.dcm import DeepCoxMixtures
# Instantiate a DCM Model with 3 phenogroups and a single hidden layer with size 100.
model = DeepCoxMixtures(k = 3, layers = [100])
model.fit(features, outcomes.time, outcomes.event, iters = 100, learning_rate = 1e4)
# Infer the latent Phenotpyes
latent_z_prob = model.predict_latent_z(features)
phenotypings = latent_z_prob.argmax(axis=1)
 Counterfactual Phenotyping: Identifies groups of individuals that demonstrate
heterogenous treatment effects. That is, the learnt phenogroups have differential
response to a specific intervention. Relies on the specially designed
DeepCoxMixturesHeterogenousEffects
latent variable model.
from auton_survival.models.cmhe DeepCoxMixturesHeterogenousEffects
# Instantiate the CMHE model
model = DeepCoxMixturesHeterogenousEffects(random_seed=random_seed, k=k, g=g, layers=layers)
model = model.fit(features, outcomes.time, outcomes.event, intervention)
zeta_probs = model.predict_latent_phi(x_tr)
zeta = np.argmax(zeta_probs, axis=1)
 Virtual Twins Phenotyping: Phenotyper that estimates the potential outcomes under treatment and control using a counterfactual Deep Cox Proportional Hazards model, followed by regressing the difference of the estimated counterfactual Restricted Mean Survival Times using a Random Forest regressor.
from auton_survival.phenotyping import SurvivalVirtualTwins
# Instantiate the Survival Virtual Twins
model = SurvivalVirtualTwins(horizon=365)
# Infer the estimated counterfactual phenotype probability.
phenotypes = model.fit_predict(features, outcomes.time, outcomes.event, interventions)
DAG representations of the unsupervised, supervised, and counterfactual probabilitic phenotypers in autonsurvival are shown in the below figure. X represents the covariates, T the timetoevent and Z is the phenotype to be inferred.
A. Unsupervised Phenotyping B. Supervised Phenotyping C. Counterfactual Phenotyping
Figure 3. DAG Representations of the Phenotypers in autonsurvival
Evaluation And Reporting
auton_survival.metrics
Helper functions to generate standard reports for common Survival Analysis tasks with support for bootstrapped confidence intervals.
 Regression Metric: Metrics for survival model performance evaluation:
 Brier Score
 Integrated Brier Score
 Area under the Receiver Operating Characteristic (ROC) Curve
 Concordance Index
from auton_survival.metrics import survival_regression_metric
# Infer eventfree survival probability from model
predictions = model.predict_survival(features, times)
# Compute Brier Score, Integrated Brier Score
# Area Under ROC Curve and Time Dependent Concordance Index
metrics = ['brs', 'ibs', 'auc', 'ctd']
score = survival_regression_metric(metric='brs', outcomes_train,
outcomes_test, predictions_test,
times=times)
 Treatment Effect: Used to compare treatment arms by computing the difference in the following metrics for treatment and control groups:
 Time at Risk (TaR)
 Risk at Time
 Restricted Mean Survival Time (RMST)
A. Time at Risk C. RMST B. Risk at Time
Figure 4. Graphical representation of the Treatment Effect Metrics
from auton_survival.metrics import survival_diff_metric
# Compute the difference in RMST, Risk at Time, and TaR between treatment and control groups
metrics = ['restricted_mean', 'survival_at', 'tar']
effect = survival_diff_metric(metric='restricted_mean', outcomes=outcomes
treatment_indicator=treatment_indicator,
weights=None, horizon=120, n_bootstrap=500)
 Phenotype Purity: Used to measure a phenotyper’s ability to extract subgroups, or phenogroups, with differential survival rates by fitting a KaplanMeier estimator within each phenogroup followed by estimating the Brier Score or Integrated Brier Score within each phenogroup.
from auton_survival.metrics import phenotype_purity
# Measure phenotype purity using the Brier Score at event horizons of 1, 2 and 5 years.
phenotype_purity(phenotypes, outcomes, strategy='instantaneous',
time=[365,730,1825])
# Measure phenotype purity using the Integrated Brier score at an event horizon of 5 years.
phenotype_purity(phenotypes, outcomes, strategy='integrated', time=1825)
auton_survival.reporting
Helper functions to generate plots for Survival Analysis tasks.
# Plot separate Kaplan Meier survival estimates for phenogroups.
auton_survival.reporting.plot_kaplanmeier(outcomes, groups=phenotypes)
# Plot separate NelsonAalen estimates for phenogroups.
auton_survival.reporting.plot_nelsonaalen(outcomes, groups=phenotypes)
Dataset Loading And Preprocessing
Helper functions to load and preprocess various timetoevent data like the
popular SUPPORT
, FRAMINGHAM
and PBC
dataset for survival analysis.
auton_survival.datasets
# Load the SUPPORT Dataset
from auton_survival.datasets import load_dataset
datasets = ['SUPPORT', 'PBC', 'FRAMINGHAM', 'MNIST', 'SYNTHETIC']
features, outcomes = datasets.load_dataset('SUPPORT')
auton_survival.preprocessing
This module provides a flexible API to perform imputation and data
normalization for downstream machine learning models. The module has
3 distinct classes, Scaler
, Imputer
and Preprocessor
. The Preprocessor
class is a composite transform that does both Imputing and Scaling with
a single function call.
# Preprocessing loaded Datasets
from auton_survival import datasets
features, outcomes = datasets.load_topcat()
from auton_survival.preprocessing import Preprocessing
features = Preprocessor().fit_transform(features,
cat_feats=['GENDER', 'ETHNICITY', 'SMOKE'],
num_feats=['height', 'weight'])
# The `cat_feats` and `num_feats` lists would contain all the categorical and numerical features in the dataset.
Citing And References
Please cite the following paper if you use the autonsurvival
package:
@article{autonsurvival,
title={autonsurvival: an OpenSource Package for Regression, Counterfactual Estimation, Evaluation and Phenotyping with Censored TimetoEvent Data},
author={Nagpal, Chirag and Potosnak, Willa and Dubrawski, Artur},
year={2022},
publisher={arXiv}
}
Additionally, autonsurvival
implements the following methodologies:
@article{nagpal2022counterfactual,
title={Counterfactual Phenotyping with Censored TimetoEvents},
author={Nagpal, Chirag and Goswami, Mononito and Dufendach, Keith and Dubrawski, Artur},
journal={arXiv preprint arXiv:2202.11089},
year={2022}
}
[3] Deep Cox Mixtures for Survival Regression. Conference on Machine Learning for Healthcare (2021)
@inproceedings{nagpal2021dcm,
title={Deep Cox mixtures for survival regression},
author={Nagpal, Chirag and Yadlowsky, Steve and Rostamzadeh, Negar and Heller, Katherine},
booktitle={Machine Learning for Healthcare Conference},
pages={674708},
year={2021},
organization={PMLR}
}
[4] Deep Parametric TimetoEvent Regression with TimeVarying Covariates. AAAI Spring Symposium (2021)
@InProceedings{pmlrv146nagpal21a,
title={Deep Parametric TimetoEvent Regression with TimeVarying Covariates},
author={Nagpal, Chirag and Jeanselme, Vincent and Dubrawski, Artur},
booktitle={Proceedings of AAAI Spring Symposium on Survival Prediction  Algorithms, Challenges, and Applications 2021},
series={Proceedings of Machine Learning Research},
publisher={PMLR},
}
@article{nagpal2021dsm,
title={Deep survival machines: Fully parametric survival regression and representation learning for censored data with competing risks},
author={Nagpal, Chirag and Li, Xinyu and Dubrawski, Artur},
journal={IEEE Journal of Biomedical and Health Informatics},
volume={25},
number={8},
pages={31633175},
year={2021},
publisher={IEEE}
}
Compatibility And Installation
auton_survival
requires python
3.5+ and pytorch
1.1+.
To evaluate performance using standard metrics
auton_survival
requires scikitsurvival
.
To install auton_survival
, clone the following git repository:
foo@bar:~$ git clone https://github.com/autonlab/autonsurvival.git
foo@bar:~$ pip install r requirements.txt
Contributing
auton_survival
is on GitHub. Bug reports and pull requests are welcome.
License
MIT License
Copyright (c) 2022 Carnegie Mellon University, Auton Lab
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Submodules
auton_survival.datasets

Utility functions to load standard datasets to train and evaluate the Deep Survival Machines models.
auton_survival.estimators

Utilities to train survival regression models and estimate survival.
auton_survival.experiments

Utilities to perform crossvalidation.
auton_survival.metrics

Tools to compute metrics used to assess survival outcomes and survival model performance.
auton_survival.models
auton_survival.phenotyping

Utilities to phenotype individuals based on similar survival characteristics.
auton_survival.preprocessing
auton_survival.reporting
auton_survival.utils