add criticism api (#382)

docs/autogen.py

@@ -111,6 +111,16 @@
         'page': 'criticism.tex',
         'title': 'Criticism',
         'parent_pages': [],
+        'child_pages': [
+            'criticism-api.tex',
+        ],
+    },
+    {
+        'page': 'criticism-api.tex',
+        'title': 'API',
+        'parent_pages': [
+            'criticism.tex'
+        ],
         'child_pages': [],
     },
     # {

docs/tex/api/criticism-api.tex

@@ -0,0 +1,13 @@
+\title{Criticism - API}
+
+{{navbar}}
+
+\subsubsection{Criticism - API}
+
+{{sphinx
+
+.. automodule:: edward.criticisms
+   :members: evaluate,
+             ppc
+
+}}

edward/criticisms/evaluate.py

@@ -14,30 +14,30 @@ def evaluate(metrics, data, latent_vars=None, model_wrapper=None,
              n_samples=100, output_key='y'):
   """Evaluate fitted model using a set of metrics.
 
-  A metric, or scoring rule, is a function of observed data under the
-  posterior predictive distribution. For example in supervised metrics
-  such as classification accuracy, the observed data (true output) is
-  compared to the posterior predictive's mean (predicted output). In
-  unsupervised metrics such as log-likelihood, the probability of
-  observing the data is calculated under the posterior predictive's
-  log-density.
+  A metric, or scoring rule (Winkler, 1994), is a function of observed
+  data under the posterior predictive distribution. For example in
+  supervised metrics such as classification accuracy, the observed
+  data (true output) is compared to the posterior predictive's mean
+  (predicted output). In unsupervised metrics such as log-likelihood,
+  the probability of observing the data is calculated under the
+  posterior predictive's log-density.
 
   Parameters
   ----------
   metrics : list of str or str
     List of metrics or a single metric.
   data : dict
     Data to evaluate model with. It binds observed variables (of type
-    `RandomVariable`) to their realizations (of type `tf.Tensor`). It
-    can also bind placeholders (of type `tf.Tensor`) used in the model
+    ``RandomVariable``) to their realizations (of type ``tf.Tensor``). It
+    can also bind placeholders (of type ``tf.Tensor``) used in the model
     to their realizations.
   latent_vars : dict of str to RandomVariable, optional
     Collection of random variables binded to their inferred posterior.
     It is only used (and in fact required) if the model wrapper is
     specified.
   model_wrapper : ed.Model, optional
     An optional wrapper for the probability model. It must have a
-    `predict` method, and `latent_vars` must be specified. `data` is
+    ``predict`` method, and ``latent_vars`` must be specified. ``data`` is
     also changed. For TensorFlow, Python, and Stan models, the key
     type is a string; for PyMC3, the key type is a Theano shared
     variable. For TensorFlow, Python, and PyMC3 models, the value type
@@ -70,8 +70,8 @@ def evaluate(metrics, data, latent_vars=None, model_wrapper=None,
   >>> evaluate('log_likelihood', data={x_post: x_train})
   >>>
   >>> # classification accuracy
-  >>> # here, `x_ph` is any features the model is defined with respect to,
-  >>> # and `y_post` is the posterior predictive distribution
+  >>> # here, ``x_ph`` is any features the model is defined with respect to,
+  >>> # and ``y_post`` is the posterior predictive distribution
   >>> evaluate('binary_accuracy', data={y_post: y_train, x_ph: x_train})
   """
   sess = get_session()

edward/criticisms/ppc.py

@@ -10,40 +10,40 @@
 
 
 def ppc(T, data, latent_vars=None, model_wrapper=None, n_samples=100):
-  """Posterior predictive check.
-  (Rubin, 1984; Meng, 1994; Gelman, Meng, and Stern, 1996)
+  """Posterior predictive check
+  (Rubin, 1984; Meng, 1994; Gelman, Meng, and Stern, 1996).
 
   If ``latent_vars`` is inputted as ``None``, then it is a prior
   predictive check (Box, 1980).
 
   PPC's form an empirical distribution for the predictive discrepancy,
 
   .. math::
-    p(T) = \int p(T(xrep) | z) p(z | x) dz
+    p(T) = \int p(T(x^{rep}) | z) p(z | x) dz
 
   by drawing replicated data sets xrep and calculating
-  :math:`T(xrep)` for each data set. Then it compares it to
+  :math:`T(x^{rep})` for each data set. Then it compares it to
   :math:`T(x)`.
 
   Parameters
   ----------
   T : function
     Discrepancy function, which takes a dictionary of data and
-    dictionary of latent variables as input and outputs a `tf.Tensor`.
+    dictionary of latent variables as input and outputs a ``tf.Tensor``.
   data : dict
     Data to compare to. It binds observed variables (of type
-    `RandomVariable`) to their realizations (of type `tf.Tensor`). It
-    can also bind placeholders (of type `tf.Tensor`) used in the model
+    ``RandomVariable``) to their realizations (of type ``tf.Tensor``). It
+    can also bind placeholders (of type ``tf.Tensor``) used in the model
     to their realizations.
   latent_vars : dict of str to RandomVariable, optional
     Collection of random variables binded to their inferred posterior.
     It is an optional argument, necessary for when the discrepancy is
     a function of latent variables.
   model_wrapper : ed.Model, optional
     An optional wrapper for the probability model. It must have a
-    ``sample_likelihood`` method. If `latent_vars` is not specified,
+    ``sample_likelihood`` method. If ``latent_vars`` is not specified,
     it must also have a ``sample_prior`` method, as ``ppc`` will
-    default to a prior predictive check. `data` is also changed. For
+    default to a prior predictive check. ``data`` is also changed. For
     TensorFlow, Python, and Stan models, the key type is a string; for
     PyMC3, the key type is a Theano shared variable. For TensorFlow,
     Python, and PyMC3 models, the value type is a NumPy array or
@@ -59,7 +59,7 @@ def ppc(T, data, latent_vars=None, model_wrapper=None, n_samples=100):
     array of size elements,
 
     .. math::
-      (T(xrep^{1}, z^{1}), ..., T(xrep^{size}, z^{size}))
+      (T(x^{rep,1}, z^{1}), ..., T(x^{rep,size}, z^{size}))
 
     and the realized discrepancy, which is a NumPy array of size
     elements,