modified: __init__.py

modified: estimators.py modified: experiments.py new file: experiments_private.py modified: phenotyping.py new file: reporting_private.py
autonlab · Mar 15, 2022 · 887aa42 · 887aa42
1 parent 02df23e
commit 887aa42
Show file tree

Hide file tree

Showing 6 changed files with 581 additions and 95 deletions.
diff --git a/auton_survival/__init__.py b/auton_survival/__init__.py
@@ -1,5 +1,6 @@
 r'''
 
+
 [![Build Status](https://travis-ci.org/autonlab/DeepSurvivalMachines.svg?branch=master)](https://travis-ci.org/autonlab/DeepSurvivalMachines)
 &nbsp;&nbsp;&nbsp;
 [![codecov](https://codecov.io/gh/autonlab/DeepSurvivalMachines/branch/master/graph/badge.svg?token=FU1HB5O92D)](https://codecov.io/gh/autonlab/DeepSurvivalMachines)
@@ -39,28 +40,26 @@
 Survival Regression
 -------------------
 
-### `auton_survival.estimators`
+Currently supported Survival Models are:
 
-This module provids a wrapper to model BioLINNC datasets with standard
-survival (time-to-event) analysis methods.
-The use of the wrapper allows a simple standard interface for multiple
-different survival models, and also helps standardize experiments across
-various differents research areas.
+### `auton_survival.models.dsm.DeepSurvivalMachines`
+### `auton_survival.models.dcm.DeepCoxMixtures`
+### `auton_survival.models.cph.DeepCoxPH`
 
-Currently supported Survival Models are:
 
-- `auton_survival.models.dsm.DeepSurvivalMachines`
-- `auton_survival.models.dcm.DeepCoxMixtures`
-- `auton_survival.models.cph.DeepCoxPH`
+### `auton_survival.estimators`
+
+This module provids a wrapper to model survival datasets with standard
+survival (time-to-event) analysis methods. The use of the wrapper allows
+a simple standard interface for multiple different survival regression methods.
 
-`auton_survival` also provides convenient wrappers around other popular
+`auton_survival.estimators` also provides convenient wrappers around other popular
 python survival analysis packages to experiment with the following
 survival regression estimators
 
 - Random Survival Forests (`pysurvival`):
 - Weibull Accelerated Failure Time (`lifelines`) :
 
-
 ### `auton_survival.experiments`
 
 Modules to perform standard survival analysis experiments. This module
@@ -155,14 +154,74 @@ class is a composite transform that does both Imputing ***and*** Scaling with
 
 ```
 
+Evaluation and Reporting
+-------------------------
 
-Reporting
-----------
-
-### `auton_survival.reporting`
+### `auton_survival.metrics`
 
 Helper functions to generate standard reports for common Survival Analysis tasks.
 
+Citing and References
+----------------------
+
+Please cite the following papers if you are using the `auton_survival` package.
+
+[1] [Deep Survival Machines:
+Fully Parametric Survival Regression and
+Representation Learning for Censored Data with Competing Risks."
+IEEE Journal of Biomedical and Health Informatics (2021)](https://arxiv.org/abs/2003.01176)</a>
+
+```
+  @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={3163--3175},
+  year={2021},
+  publisher={IEEE}
+  }
+```
+
+[2] [Deep Parametric Time-to-Event Regression with Time-Varying Covariates. AAAI
+Spring Symposium (2021)](http://proceedings.mlr.press/v146/nagpal21a.html)</a>
+
+```
+  @InProceedings{pmlr-v146-nagpal21a,
+  title={Deep Parametric Time-to-Event Regression with Time-Varying 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},
+  }
+```
+
+[3] [Deep Cox Mixtures for Survival Regression. Conference on Machine Learning for
+Healthcare (2021)](https://arxiv.org/abs/2101.06536)</a>
+
+```
+  @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={674--708},
+  year={2021},
+  organization={PMLR}
+  }
+```
+
+[4] [Counterfactual Phenotyping with Censored Time-to-Events (2022)](https://arxiv.org/abs/2202.11089)</a>
+
+```
+  @article{nagpal2022counterfactual,
+  title={Counterfactual Phenotyping with Censored Time-to-Events},
+  author={Nagpal, Chirag and Goswami, Mononito and Dufendach, Keith and Dubrawski, Artur},
+  journal={arXiv preprint arXiv:2202.11089},
+  year={2022}
+  }
+```
+
 ## Installation
 
 ```console
@@ -207,17 +266,18 @@ class is a composite transform that does both Imputing ***and*** Scaling with
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
-
 <img style="float: right;" height="150px" src="https://www.cmu.edu/brand/\
 downloads/assets/images/wordmarks-600x600-min.jpg">
 <img style="float: right;padding-top:30px" height="110px"
 src="https://www.cs.cmu.edu/~chiragn/auton_logo.png">
 
-<br><br><br><br><br>
 <br><br><br><br><br>
 
 '''
 
+__version__ = "0.1.0"
+
+
 from .models.dsm import DeepSurvivalMachines
 from .models.dcm import DeepCoxMixtures
 from .models.cph import DeepCoxPH, DeepRecurrentCoxPH

diff --git a/auton_survival/estimators.py b/auton_survival/estimators.py
@@ -27,6 +27,7 @@
 import pandas as pd
 
 def _get_valid_idx(n, size, random_seed):
+
   """Randomly select sample indices to split into train and test data.
 
   Parameters:
@@ -44,7 +45,6 @@ def _get_valid_idx(n, size, random_seed):
 
   """
 
-  import numpy as np
   np.random.seed(random_seed)
 
 
@@ -213,10 +213,10 @@ def _fit_dcph(features, outcomes, random_seed, **hyperparams):
       - 'activation' : str, default='relu'
           Activation function
           Options include: 'relu', 'relu6', 'tanh'
-  
+ 
   Return:
   -----------
-  Trained instance of the Deep Cox Mixtures model.
+  Trained instance of the Deep Cox Proportional Hazards model.
 
   """
 
@@ -460,7 +460,7 @@ def _fit_dsm(features, outcomes, random_seed, **hyperparams):
 
   from .models.dsm import DeepSurvivalMachines
 
-  k = hyperparams.get("k", 3) 
+  k = hyperparams.get("k", 3)
   layers = hyperparams.get("layers", [100])
   iters = hyperparams.get("iters", 10)
   distribution = hyperparams.get("distribution", "Weibull")
@@ -470,7 +470,7 @@ def _fit_dsm(features, outcomes, random_seed, **hyperparams):
                                distribution=distribution,
                                temp=temperature)
 
-  model.fit(features.values, 
+  model.fit(features.values,
             outcomes['time'].values,
             outcomes['event'].values,
             iters=iters)
@@ -589,25 +589,37 @@ class SurvivalModel:
 
   """Universal interface to train multiple different survival models.
 
-  Choices include:
+  Parameters
+  -----------
+  model : str
+      A string that determines the choice of the surival analysis model.
+      Survival model choices include:
+
+      - 'dsm' : Deep Survival Machines [3] model
+      - 'dcph' : Deep Cox Proportional Hazards [2] model
+      - 'dcm' : Deep Cox Mixtures [4] model
+      - 'rsf' : Random Survival Forests [1] model
+      - 'cph' : Cox Proportional Hazards [2] model
+
+  random_seed: int
+      Controls the reproducibility of called functions.
 
-  - 'rsf' : Random Survival Forests [1] model
-  - 'cph' : Cox Proportional Hazards [2] model
-  - 'dsm' : Deep Survival Machines [3] model
-  - 'dcph' : Deep Cox Mixtures [4] model
-  - 'dcm' : Deep Cox Mixtures [4] model
 
   References
   -----------
+
   [1] Hemant Ishwaran et al. Random survival forests.
   The annals of applied statistics, 2(3):841–860, 2008.
+
   [2] Cox, D. R. (1972). Regression models and life-tables.
   Journal of the Royal Statistical Society: Series B (Methodological).
+
   [3] Chirag Nagpal, Xinyu Li, and Artur Dubrawski.
   Deep survival machines: Fully parametric survival regression and
   representation learning for censored data with competing risks. 2020.
+
   [4] Nagpal, C., Yadlowsky, S., Rostamzadeh, N., and Heller, K. (2021c).
-  Deep cox mixtures for survival regression. 
+  Deep cox mixtures for survival regression.
   In Machine Learning for Healthcare Conference, pages 674–708. PMLR
 
   """
@@ -627,17 +639,18 @@ def fit(self, features, outcomes):
 
     """This method is used to train an instance of the survival model.
 
-    Parameter
+    Parameters
     -----------
-    features : pd.DataFrame
-        A pandas dataframe with rows corresponding to individual samples and
+    features: pd.DataFrame
+        a pandas dataframe with rows corresponding to individual samples and
         columns as covariates.
     outcomes : pd.DataFrame
-        A pandas dataframe with columns 'time' and 'event'.
+        a pandas dataframe with columns 'time' and 'event'.
 
     Returns
-    -----------
-    Trained instance of the survival model.
+    --------
+    self
+        Trained instance of a survival model.
 
     """
 
@@ -655,14 +668,14 @@ def predict_survival(self, features, times):
 
     """Predict survival probabilities at specified time(s).
 
-    Parameter
+    Parameters
     -----------
-    features : pd.DataFrame
-        A pandas dataframe with rows corresponding to individual samples
+    features: pd.DataFrame
+        a pandas dataframe with rows corresponding to individual samples
         and columns as covariates.
     times: float or list
-        A float or list of the times at which to compute the survival probability.
-  
+        a float or list of the times at which to compute the survival probability.
+
     """
 
     if self.model == 'cph': return _predict_cph(self._model, features, times)
@@ -676,17 +689,18 @@ def predict_risk(self, features, times):
 
     """Predict risk of an outcome occurring within the specified time(s).
 
-    Parameter
+    Parameters
     -----------
     features : pd.DataFrame
-        A pandas dataframe with rows corresponding to individual samples and
+        a pandas dataframe with rows corresponding to individual samples and
         columns as covariates.
     times: float or list
-        A float or list of the times at which to compute the risk.
+        a float or list of the times at which to compute the risk.
 
     Returns
-    -----------
-    np.array : numpy array of the outcome risks at each time point in times.
+    ---------
+    np.array
+        numpy array of the outcome risks at each time point in times.
 
     """