Merge 545a05f into d7f19d2

.travis.yml

@@ -28,7 +28,7 @@ install:
   - conda create -n test-environment python=$TRAVIS_PYTHON_VERSION pip numpy scipy pandas matplotlib pytest
   - source activate test-environment
   # Build in place so we can run tests
-  - python setup.py build_ext --inplace
+  - python setup.py install
   - pip install coveralls
   - pip install pytest-cov
 # command to run tests

CHANGELOG.md

@@ -1,5 +1,15 @@
 ### Changelogs
 
+#### 0.8.0
+ - reorganized lifelines directories: 
+    - moved test files out of main directory. 
+    - moved `utils.py` into it's down directory.
+    - moved all estimators `fitters` directory.
+ - added a `at_risk` column to the output of `group_survival_table_from_events` and `survival_table_from_events`
+ - added sample size and power calculations for statistical tests. See `lifeline.statistics. sample_size_necessary_under_cph` and `lifelines.statistics. power_under_cph`. 
+ - fixed a bug when using KaplanMeierFitter for left-censored data. 
+
+
 #### 0.7.1 
 - addition of a l2 `penalizer` to `CoxPHFitter`.
 - dropped Fortran implementation of efficient Python version. Lifelines is pure python once again!

docs/Examples.rst

@@ -156,6 +156,27 @@ time (months, days, ...)      observed deaths       censored
     print C # np.array([1,1,1,1,1,1,1,0,1,1, ...])
 
 
+Alternatively, perhaps you are interested in viewing the survival table given some durations and censorship vectors.
+
+
+.. code:: python
+    
+    from lifelines.utils import survival_table_from_events
+
+    table = survival_table_from_events(T, C)
+    print table.head()
+    
+    """
+              removed  observed  censored  entrance  at_risk
+    event_at
+    0               0         0         0        60       60
+    2               2         1         1         0       60
+    3               3         1         2         0       58
+    4               5         3         2         0       55
+    5              12         6         6         0       50
+    """
+
+
 
 Plotting multiple figures on an plot 
 ##############################################

docs/Quickstart.rst

@@ -114,6 +114,27 @@ Lifelines has some utility functions to transform this dataset into durations an
     T, C = datetimes_to_durations(start_times, end_times, freq='h')
 
 
+Alternatively, perhaps you are interested in viewing the survival table given some durations and censorship vectors.
+
+
+.. code:: python
+    
+    from lifelines.utils import survival_table_from_events
+
+    table = survival_table_from_events(T, C)
+    print table.head()
+
+    """
+              removed  observed  censored  entrance  at_risk
+    event_at
+    0               0         0         0        60       60
+    2               2         1         1         0       60
+    3               3         1         2         0       58
+    4               5         3         2         0       55
+    5              12         6         6         0       50
+    """
+
+
 Survival Regression
 ---------------------------------
 

lifelines/estimation.py

@@ -1,9 +1,9 @@
 # -*- coding: utf-8 -*-
-from lifelines._base_fitter import BaseFitter
-from lifelines.weibull_fitter import WeibullFitter
-from lifelines.exponential_fitter import ExponentialFitter
-from lifelines.nelson_aalen_fitter import NelsonAalenFitter
-from lifelines.kaplan_meier_fitter import KaplanMeierFitter
-from lifelines.breslow_fleming_harrington_fitter import BreslowFlemingHarringtonFitter
-from lifelines.coxph_fitter import CoxPHFitter
-from lifelines.aalen_additive_fitter import AalenAdditiveFitter
+from lifelines.fitters import BaseFitter
+from lifelines.fitters.weibull_fitter import WeibullFitter
+from lifelines.fitters.exponential_fitter import ExponentialFitter
+from lifelines.fitters.nelson_aalen_fitter import NelsonAalenFitter
+from lifelines.fitters.kaplan_meier_fitter import KaplanMeierFitter
+from lifelines.fitters.breslow_fleming_harrington_fitter import BreslowFlemingHarringtonFitter
+from lifelines.fitters.coxph_fitter import CoxPHFitter
+from lifelines.fitters.aalen_additive_fitter import AalenAdditiveFitter

lifelines/_base_fitter.py → lifelines/fitters/__init__.py

@@ -1,7 +1,9 @@
 # -*- coding: utf-8 -*-
 from __future__ import print_function
+
 import numpy as np
 import pandas as pd
+
 from lifelines.plotting import plot_estimate
 from lifelines.utils import qth_survival_times
 

lifelines/aalen_additive_fitter.py → lifelines/fitters/aalen_additive_fitter.py

@@ -1,13 +1,15 @@
 # -*- coding: utf-8 -*-
 from __future__ import print_function
+
 import numpy as np
 import pandas as pd
 from numpy.linalg import LinAlgError
 from scipy.integrate import trapz
-from lifelines._base_fitter import BaseFitter
+
+from lifelines.fitters import BaseFitter
 from lifelines.utils import _get_index, inv_normal_cdf, epanechnikov_kernel, \
     ridge_regression as lr, qth_survival_times
-from lifelines.progress_bar import progress_bar
+from lifelines.utils.progress_bar import progress_bar
 from lifelines.plotting import plot_regressions
 
 

lifelines/breslow_fleming_harrington_fitter.py → lifelines/fitters/breslow_fleming_harrington_fitter.py

@@ -2,8 +2,8 @@
 from __future__ import print_function
 import numpy as np
 
-from lifelines._base_fitter import UnivariateFitter
-from lifelines.nelson_aalen_fitter import NelsonAalenFitter
+from lifelines.fitters import UnivariateFitter
+from lifelines.fitters.nelson_aalen_fitter import NelsonAalenFitter
 from lifelines.utils import median_survival_times
 
 

lifelines/coxph_fitter.py → lifelines/fitters/coxph_fitter.py

@@ -8,7 +8,7 @@
 from scipy.integrate import trapz
 import scipy.stats as stats
 
-from lifelines._base_fitter import BaseFitter
+from lifelines.fitters import BaseFitter
 from lifelines.utils import survival_table_from_events, inv_normal_cdf, normalize,\
     significance_code, concordance_index, _get_index, qth_survival_times
 

lifelines/exponential_fitter.py → lifelines/fitters/exponential_fitter.py

@@ -3,7 +3,7 @@
 import numpy as np
 import pandas as pd
 
-from lifelines._base_fitter import UnivariateFitter
+from lifelines.fitters import UnivariateFitter
 from lifelines.utils import inv_normal_cdf
 
 

lifelines/kaplan_meier_fitter.py → lifelines/fitters/kaplan_meier_fitter.py

@@ -3,7 +3,7 @@
 import numpy as np
 import pandas as pd
 
-from lifelines._base_fitter import UnivariateFitter
+from lifelines.fitters import UnivariateFitter
 from lifelines.utils import _preprocess_inputs, _additive_estimate, StatError, inv_normal_cdf,\
     median_survival_times
 

lifelines/nelson_aalen_fitter.py → lifelines/fitters/nelson_aalen_fitter.py

@@ -3,7 +3,7 @@
 import numpy as np
 import pandas as pd
 
-from lifelines._base_fitter import UnivariateFitter
+from lifelines.fitters import UnivariateFitter
 from lifelines.utils import _preprocess_inputs, _additive_estimate, epanechnikov_kernel,\
     inv_normal_cdf
 

lifelines/weibull_fitter.py → lifelines/fitters/weibull_fitter.py

@@ -2,10 +2,12 @@
 from __future__ import print_function, division
 import numpy as np
 import pandas as pd
+
 from numpy.linalg import solve, norm, inv
-from lifelines._base_fitter import UnivariateFitter
+from lifelines.fitters import UnivariateFitter
 from lifelines.utils import inv_normal_cdf
 
+
 def _negative_log_likelihood(lambda_rho, T, E):
     if np.any(lambda_rho < 0):
         return np.inf

lifelines/plotting.py

@@ -2,7 +2,7 @@
 from __future__ import print_function
 
 import numpy as np
-from lifelines.utils import coalesce
+from .utils import coalesce
 
 
 def is_latex_enabled():

lifelines/statistics.py

@@ -9,6 +9,64 @@
 from lifelines.utils import group_survival_table_from_events
 
 
+def sample_size_necessary_under_cph(power, ratio_of_participants, p_exp, p_con,
+                                    postulated_hazard_ratio, alpha=0.05):
+    """
+    This computes the sample size for needed power to compare two groups under a Cox
+    Proportional Hazard model.
+
+    References:
+        https://cran.r-project.org/web/packages/powerSurvEpi/powerSurvEpi.pdf
+
+    Parameters:
+        power: power to detect the magnitude of the hazard ratio as small as that specified by postulated_hazard_ratio.
+        ratio_of_participants: ratio of participants in experimental group over control group.
+        p_exp: probability of failure in experimental group over period of study.
+        p_con: probability of failure in control group over period of study
+        postulated_hazard_ratio: the postulated hazard ratio
+        alpha: type I error rate
+
+    Returns:
+        n_exp, n_con: the samples sizes need for the experiment and control group, respectively, to achieve desired power
+    """
+    z = lambda p: stats.norm.ppf(p)
+
+    m = 1.0 / ratio_of_participants \
+        * ((ratio_of_participants * postulated_hazard_ratio + 1.0) / (postulated_hazard_ratio - 1.0)) ** 2 \
+        * (z(1. - alpha / 2.) + z(power)) ** 2
+
+    n_exp = m * ratio_of_participants / (ratio_of_participants * p_exp + p_con)
+    n_con = m / (ratio_of_participants * p_exp + p_con)
+
+    return int(np.ceil(n_exp)), int(np.ceil(n_con))
+
+
+def power_under_cph(n_exp, n_con, p_exp, p_con, postulated_hazard_ratio, alpha=0.05):
+    """
+    This computes the sample size for needed power to compare two groups under a Cox
+    Proportional Hazard model.
+
+    References:
+        https://cran.r-project.org/web/packages/powerSurvEpi/powerSurvEpi.pdf
+
+    Parameters:
+        n_exp: size of the experiment group.
+        n_con: size of the control group.
+        p_exp: probability of failure in experimental group over period of study.
+        p_con: probability of failure in control group over period of study
+        postulated_hazard_ratio: the postulated hazard ratio
+        alpha: type I error rate
+
+    Returns:
+        power: power to detect the magnitude of the hazard ratio as small as that specified by postulated_hazard_ratio.
+    """
+    z = lambda p: stats.norm.ppf(p)
+
+    m = n_exp * p_exp + n_con * p_con
+    k = float(n_exp) / float(n_con)
+    return stats.norm.cdf(np.sqrt(k * m) * abs(postulated_hazard_ratio - 1) / (k * postulated_hazard_ratio + 1) - z(1 - alpha / 2.))
+
+
 def logrank_test(event_times_A, event_times_B, event_observed_A=None, event_observed_B=None,
                  alpha=0.95, t_0=-1, **kwargs):
     """