Time-to-event prediction with PyTorch
Get Started • Methods • Evaluation Criteria • Datasets • Installation • References
**pycox** is a python package for survival analysis and time-to-event prediction with [PyTorch](https://pytorch.org), built on the [torchtuples](https://github.com/havakv/torchtuples) package for training PyTorch models. An R version of this package is available at [survivalmodels](https://github.com/RaphaelS1/survivalmodels). The package contains implementations of various [survival models](#methods), some useful [evaluation metrics](#evaluation-criteria), and a collection of [event-time datasets](#datasets). In addition, some useful preprocessing tools are available in the `pycox.preprocessing` module. # Get Started To get started you first need to install [PyTorch](https://pytorch.org/get-started/locally/). You can then install **pycox** via pip: ```sh pip install pycox ``` OR, via conda: ```sh conda install -c conda-forge pycox ``` We recommend to start with [01_introduction.ipynb](https://nbviewer.jupyter.org/github/havakv/pycox/blob/master/examples/01_introduction.ipynb), which explains the general usage of the package in terms of preprocessing, creation of neural networks, model training, and evaluation procedure. The notebook use the `LogisticHazard` method for illustration, but most of the principles generalize to the other methods. Alternatively, there are many examples listed in the [examples folder](https://nbviewer.jupyter.org/github/havakv/pycox/tree/master/examples), or you can follow the tutorial based on the `LogisticHazard`: - [01_introduction.ipynb](https://nbviewer.jupyter.org/github/havakv/pycox/blob/master/examples/01_introduction.ipynb): General usage of the package in terms of preprocessing, creation of neural networks, model training, and evaluation procedure. - [02_introduction.ipynb](https://nbviewer.jupyter.org/github/havakv/pycox/blob/master/examples/02_introduction.ipynb): Quantile based discretization scheme, nested tuples with `tt.tuplefy`, entity embedding of categorical variables, and cyclical learning rates. - [03_network_architectures.ipynb](https://nbviewer.jupyter.org/github/havakv/pycox/blob/master/examples/03_network_architectures.ipynb): Extending the framework with custom networks and custom loss functions. The example combines an autoencoder with a survival network, and considers a loss that combines the autoencoder loss with the loss of the `LogisticHazard`. - [04_mnist_dataloaders_cnn.ipynb](https://nbviewer.jupyter.org/github/havakv/pycox/blob/master/examples/04_mnist_dataloaders_cnn.ipynb): Using dataloaders and convolutional networks for the MNIST data set. We repeat the [simulations](https://peerj.com/articles/6257/#p-41) of [\[8\]](#references) where each digit defines the scale parameter of an exponential distribution. # Methods The following methods are available in the `pycox.methods` module. ## Continuous-Time Models:| Method | Description | Example |
|---|---|---|
| CoxTime | Cox-Time is a relative risk model that extends Cox regression beyond the proportional hazards [1]. | notebook |
| CoxCC | Cox-CC is a proportional version of the Cox-Time model [1]. | notebook |
| CoxPH (DeepSurv) | CoxPH is a Cox proportional hazards model also referred to as DeepSurv [2]. | notebook |
| PCHazard | The Piecewise Constant Hazard (PC-Hazard) model [12] assumes that the continuous-time hazard function is constant in predefined intervals. It is similar to the Piecewise Exponential Models [11] and PEANN [14], but with a softplus activation instead of the exponential function. | notebook |
| Method | Description | Example |
|---|---|---|
| LogisticHazard (Nnet-survival) | The Logistic-Hazard method parametrize the discrete hazards and optimize the survival likelihood [12] [7]. It is also called Partial Logistic Regression [13] and Nnet-survival [8]. | notebook |
| PMF | The PMF method parametrize the probability mass function (PMF) and optimize the survival likelihood [12]. It is the foundation of methods such as DeepHit and MTLR. | notebook |
| DeepHit, DeepHitSingle | DeepHit is a PMF method with a loss for improved ranking that can handle competing risks [3]. | single competing |
| MTLR (N-MTLR) | The (Neural) Multi-Task Logistic Regression is a PMF methods proposed by [9] and [10]. | notebook |
| BCESurv | A method representing a set of binary classifiers that remove individuals as they are censored [15]. The loss is the binary cross entropy of the survival estimates at a set of discrete times, with targets that are indicators of surviving each time. | bs_example |
| Metric | Description |
|---|---|
| concordance_td | The time-dependent concordance index evaluated at the event times [4]. |
| brier_score | The IPCW Brier score (inverse probability of censoring weighted Brier score) [5][6][15]. See Section 3.1.2 of [15] for details. |
| nbll | The IPCW (negative) binomial log-likelihood [5][1]. I.e., this is minus the binomial log-likelihood and should not be confused with the negative binomial distribution. The weighting is performed as in Section 3.1.2 of [15] for details. |
| integrated_brier_score | The integrated IPCW Brier score. Numerical integration of the `brier_score` [5][6]. |
| integrated_nbll | The integrated IPCW (negative) binomial log-likelihood. Numerical integration of the `nbll` [5][1]. |
| brier_score_admin integrated_brier_score_admin | The administrative Brier score [15]. Works well for data with administrative censoring, meaning all censoring times are observed. See this example notebook. |
| nbll_admin integrated_nbll_admin | The administrative (negative) binomial log-likelihood [15]. Works well for data with administrative censoring, meaning all censoring times are observed. See this example notebook. |
| Dataset | Size | Dataset | Data source |
|---|---|---|---|
| flchain | 6,524 | The Assay of Serum Free Light Chain (FLCHAIN) dataset. See [1] for preprocessing. | source |
| gbsg | 2,232 | The Rotterdam & German Breast Cancer Study Group. See [2] for details. | source |
| kkbox | 2,814,735 | A survival dataset created from the WSDM - KKBox's Churn Prediction Challenge 2017 with administrative censoring. See [1] and [15] for details. Compared to kkbox_v1, this data set has more covariates and censoring times. Note: You need Kaggle credentials to access the dataset. | source |
| kkbox_v1 | 2,646,746 | A survival dataset created from the WSDM - KKBox's Churn Prediction Challenge 2017. See [1] for details. This is not the preferred version of this data set. Use kkbox instead. Note: You need Kaggle credentials to access the dataset. | source |
| metabric | 1,904 | The Molecular Taxonomy of Breast Cancer International Consortium (METABRIC). See [2] for details. | source |
| nwtco | 4,028 | Data from the National Wilm's Tumor (NWTCO). | source |
| support | 8,873 | Study to Understand Prognoses Preferences Outcomes and Risks of Treatment (SUPPORT). See [2] for details. | source |
| Dataset | Size | Dataset | Data source |
|---|---|---|---|
| rr_nl_nph | 25,000 | Dataset from simulation study in [1]. This is a continuous-time simulation study with event times drawn from a relative risk non-linear non-proportional hazards model (RRNLNPH). | SimStudyNonLinearNonPH |
| sac3 | 100,000 | Dataset from simulation study in [12]. This is a discrete time dataset with 1000 possible event-times. | SimStudySACCensorConst |
| sac_admin5 | 50,000 | Dataset from simulation study in [15]. This is a discrete time dataset with 1000 possible event-times. Very similar to `sac3`, but with fewer survival covariates and administrative censoring determined by 5 covariates. | SimStudySACAdmin |