refs #17 : add - description about utility functions

python/wtte/tte_util.py

@@ -34,6 +34,10 @@ def roll_fun(x, size, fun=np.mean, reverse=False):
 def carry_forward_if(x, is_true):
     """Locomote forward object x[i] if is_true[i].
         remain x untouched before first pos of truth.
+        
+        :param Array x: forward object x
+        :param Array is_true: array containing true/false boolean index.
+        :return Array x:forward object x
     """
     for i in xrange(len(x)):
         if is_true[i]:
@@ -46,6 +50,10 @@ def carry_forward_if(x, is_true):
 def carry_backward_if(x, is_true):
     """Locomote backward object x[i] if is_true[i].
         remain x untouched after last pos of truth.
+
+        :param Array x: backward object x
+        :param Array is_true: array containing true/false boolean index.
+        :return Array x: backward object x
     """
     for i in xrange(reversed(len(x))):
         if is_true[i]:
@@ -57,6 +65,8 @@ def carry_backward_if(x, is_true):
 
 def steps_since_true_minimal(is_event):
     """(Time) since event over discrete (padded) events.
+    
+        :param Array is_event:  
     """
     n = len(is_event)
     z = -1  # at the latest on step before
@@ -70,6 +80,9 @@ def steps_since_true_minimal(is_event):
 
 def steps_to_true_minimal(is_event):
     """(Time) to event for discrete (padded) events.
+    
+        :param Array is_event:
+        :return Array x:
     """
     n = len(is_event)
     z = n  # at the earliest on step after
@@ -88,10 +101,10 @@ def get_tte_discrete(is_event, t_elapsed=None):
             Step of event has tte = 0
            (event happened at time [t,t+1))
             tte[-1]=1 if no event (censored data)
-        Args:
-            is_event : bolean array
-            t_elapsed : int array same length as is_event.
-                if None it's taken to be xrange(len(is_event))
+
+        :param Array is_event: Boolean array
+        :param IntArray t_elapsed: integer array with same length as `is_event`. If none, it will use `xrange(len(is_event))`
+        :return Array tte: Time-to-event array (discrete version)
     """
     n = len(is_event)
     tte = np.int32(is_event)
@@ -116,10 +129,9 @@ def get_tte_continuous(is_event, t_elapsed):
             tte[-1]=0 always
             (since last time is a *point*)
             Last datpoints are right censored.
-        Args:
-            is_event : bolean array
-            t_elapsed : array same length as is_event
-                that supports vectorized subtraction
+        :param Array is_event: Boolean array
+        :param IntArray t_elapsed: integer array with same length as `is_event` that supports vectorized subtraction. If none, it will use `xrange(len(is_event))`
+        :return Array tte: Time-to-event (continuous version) 
     """
     n = len(is_event)
     if t_elapsed is None:
@@ -136,7 +148,9 @@ def get_tte_continuous(is_event, t_elapsed):
 
 
 def get_tte(is_event, discrete_time, t_elapsed=None):
-    """(wrapper) calculates Time To Event for input vector.
+    """ wrapper to calculate Time To Event for input vector.
+
+        :param Boolean discrete_time: if `True`, use `get_tte_discrete`. If `False`, use `get_tte_continuous`.
     """
     if discrete_time:
         return get_tte_discrete(is_event, t_elapsed)
@@ -145,7 +159,7 @@ def get_tte(is_event, discrete_time, t_elapsed=None):
 
 
 def get_tse(is_event, t_elapsed=None):
-    """(wrapper) calculates Time Since Event for input vector.
+    """ Wrapper to calculate Time Since Event for input vector.
 
         Inverse of tte. Safe to use as a feature.
         Always "continuous" method of calculating it.
@@ -154,8 +168,12 @@ def get_tse(is_event, t_elapsed=None):
             we know at record of event so superfluous to have tse=0)
         tse = 0 at first step
 
-        TODO reverse-indexing is pretty slow and ugly and not a
+        TODO: reverse-indexing is pretty slow and ugly and not a
         helpful template for implementing in other languages.
+
+
+        :param Array is_event: Boolean array
+        :param IntArray t_elapsed: integer array with same length as `is_event` . If none, it will use `t_elapsed.max() - t_elapsed[::-1]`.
     """
     if t_elapsed is not None:
         t_elapsed = t_elapsed.max() - t_elapsed[::-1]
@@ -165,6 +183,8 @@ def get_tse(is_event, t_elapsed=None):
 
 def get_is_not_censored(is_event, discrete_time=True):
     """ Calculates non-censoring indicator u
+
+        :param Boolean discrete_time: if `True`, last observation is conditionally censored.
     """
     n = len(is_event)
     is_not_censored = np.copy(is_event)