refs #17 : add - comments on objective functions for TensorFlow

python/wtte/objectives/tensorflow.py

@@ -1,28 +1,29 @@
+""" Objective functions for TensorFlow
+"""
 from __future__ import absolute_import
 from __future__ import division
 from __future__ import print_function
 import tensorflow as tf
 
 
 def loglik_continuous(a, b, y_, u_, output_collection=(), name=None):
-    """Returns element-wise Weibull censored log-likelihood.
+    """ Returns element-wise Weibull censored log-likelihood.
 
     Continuous weibull log-likelihood. loss=-loglikelihood.
     All input values must be of same type and shape.
 
-    Args:
-        a:  alpha. Positive nonzero `Tensor` of type `float32`, `float64`.
-        b:  beta.  Positive nonzero `Tensor` of type `float32`, `float64`.
-        y_: time to event. Positive  nonzero `Tensor` of type `float32`, 
-            `float64`.
-        u_: indicator 0.0 if right censored, 1.0 if uncensored
-            `Tensor` of type `float32`, `float64`.
-        output_collection: `tuple` of `string`s, name of the collection to
-                          collect result of this op.
-        name: `string`, name of the operation.
-
-    Returns:
-        A `Tensor` of log-likelihoods of same shape as a, b, y_, u_
+    :param a:alpha. Positive nonzero `Tensor`.
+    :type a: `float32` or `float64`.
+    :param b:beta.  Positive nonzero `Tensor`.
+    :type b: `float32` or `float64`.
+    :param y_: time to event. Positive nonzero `Tensor` 
+    :type y_: `float32` or `float64`.
+    :param u_: indicator. 0.0 if right censored, 1.0 if uncensored `Tensor`
+    :type u_: `float32` or `float64`.
+    :param output_collection:name of the collection to collect result of this op.
+    :type output_collection: Tuple of Strings.
+    :param String name: name of the operation.
+    :return: A `Tensor` of log-likelihoods of same shape as a, b, y_, u_
     """
 
     with tf.name_scope(name, "weibull_loglik_continuous", [a, b, y_, u_]):
@@ -40,19 +41,22 @@ def loglik_discrete(a, b, y_, u_, output_collection=(), name=None):
     """Returns element-wise Weibull censored discrete log-likelihood.
 
     Unit-discretized weibull log-likelihood. loss=-loglikelihood.
-    All input values must be of same type and shape.
-
-    Args:
-        a:  alpha. Positive nonzero `Tensor` of type `float32`, `float64`.
-        b:  beta.  Positive nonzero `Tensor` of type `float32`, `float64`.
-        y_: time to event. Positive `Tensor` of type `float32`, `float64`.
-        u_: indicator 0.0 if right censored, 1.0 if uncensored
-            `Tensor` of type `float32`, `float64`.
-        output_collection: `tuple` of `string`s, name of the collection to
-                          collect result of this op.
-        name: `string`, name of the operation.
-    Returns:
-        A `Tensor` of log-likelihoods of same shape as a, b, y_, u_
+    
+    .. note::
+        All input values must be of same type and shape.
+
+    :param a:alpha. Positive nonzero `Tensor`.
+    :type a: `float32` or `float64`.
+    :param b:beta.  Positive nonzero `Tensor`.
+    :type b: `float32` or `float64`.
+    :param y_: time to event. Positive nonzero `Tensor` 
+    :type y_: `float32` or `float64`.
+    :param u_: indicator. 0.0 if right censored, 1.0 if uncensored `Tensor`
+    :type u_: `float32` or `float64`.
+    :param output_collection:name of the collection to collect result of this op.
+    :type output_collection: Tuple of Strings.
+    :param String name: name of the operation.
+    :return: A `Tensor` of log-likelihoods of same shape as a, b, y_, u_.
     """
 
     with tf.name_scope(name, "weibull_loglik_discrete", [a, b, y_, u_]):
@@ -71,14 +75,12 @@ def betapenalty(b, location=10.0, growth=20.0, output_collection=(), name=None):
     Adding this term to the loss may prevent overfitting and numerical instability
     of large values of beta (overconfidence). Remember that loss = -loglik+penalty
 
-    Args:
-        b:  beta.  Positive nonzero `Tensor` of type `float32`, `float64`.
-        output_collection: `tuple` of `string`s, name of the collection to
-                          collect result of this op.
-        name: `string`, name of the operation.
-
-    Returns:
-        A positive `Tensor` of same shape as `b` being a penalty term
+    :param b:beta.  Positive nonzero `Tensor`.
+    :type b: `float32` or `float64`.
+    :param output_collection:name of the collection to collect result of this op.
+    :type output_collection: Tuple of Strings.
+    :param String name: name of the operation.
+    :return:  A positive `Tensor` of same shape as `b` being a penalty term.
     """
     with tf.name_scope(name, "weibull_betapenalty", [a, b, y_, u_]):
         scale = growth / location