updating docs

Author: bwengals

docs/source/gp.rst

@@ -77,7 +77,7 @@ three predictor variables::
     ls = [2, 5] # the lengthscales
     cov_func = pm.gp.cov.ExpQuad(input_dim=3, ls=ls, active_dims=[1, 2])
 
-Here the :code:`ls` parameter is two dimensional, allowing the second
+Here the :code:`ls`, or lengthscale, parameter is two dimensional, allowing the second
 and third dimension to have a different lengthscale.  The reason we have to
 specify :code:`input_dim`, the total number of columns of :code:`X`, and
 :code:`active_dims`, which of those columns or dimensions the covariance
@@ -152,16 +152,7 @@ variable representing the function we are placing the prior over.
 The second argument is the inputs to the function that the prior is over, 
 :code:`X`.  The inputs are usually known and present in the data, but they can
 also be PyMC3 random variables.  If the inputs are a Theano tensor or a 
-PyMC3 random variable, the :code:`n_points` argument is required.
-
-.. note::
-
-  The :code:`n_points` argument is sometimes required due to how Theano and 
-  PyMC3 handle the shape information of distributions.  It needs to be specified
-  when :code:`X` or :code:`Xnew` is a Theano tensor or a random variable. 
-  For :code:`prior` or :code:`marginal_likelihood`, it is the number of rows
-  of the inputs, :code:`X`.  For :code:`conditional`, it is the number of 
-  rows in the new inputs, :code:`X_new`.
+PyMC3 random variable, the :code:`shape` needs to be given.
 
 Usually at this point, inference is performed on the model.  The 
 :code:`conditional` method creates the conditional, or predictive,
@@ -214,8 +205,8 @@ with the contribution due to :math:`f_1 + f_2` factored out, we get
     K_1^{**} - K_1^{*^T}(K_1 + K_2)^{-1}K_1^* \right) \,.
 
 
-So one can break down GP models into individual components to examine how each
-contribute to the data.  For more information, check out `David Duvenaud's PhD
+These equations show how to break down GP models into individual components to see how each
+contributes to the data.  For more information, check out `David Duvenaud's PhD
 thesis <https://www.cs.toronto.edu/~duvenaud/thesis.pdf>`_.
 
 The GP objects in PyMC3 keeps track of these marginals automatically.  The
@@ -225,8 +216,8 @@ other implementations.  The first block fits the GP prior.  We denote
 :math:`f_1 + f_2` as just :math:`f` for brevity::
 
     with pm.Model() as model:
-        gp1 = pm.gp.Latent(mean_func1, cov_func1)
-        gp2 = pm.gp.Latent(mean_func2, cov_func2)
+        gp1 = pm.gp.Marginal(mean_func1, cov_func1)
+        gp2 = pm.gp.Marginal(mean_func2, cov_func2)
         
         # gp represents f1 + f2.  
         gp = gp1 + gp2
@@ -236,33 +227,33 @@ other implementations.  The first block fits the GP prior.  We denote
         trace = pm.sample(1000)
 
 
-The second block produces conditional distributions, including :math:`f_2^*
-\mid f_1 + f_2`.  Notice that extra arguments are required for conditionals of
-:math:`f1` and :math:`f2`, but not :math:`f`.  This is because those arguments
-are cached when calling :code:`.marginal_likelihood`.
-
 To construct the conditional distribution of :code:`gp1` or :code:`gp2`, we 
 also need to include the additional arguments, :code:`X`, :code:`y`, and 
 :code:`noise`::
 
     with model:
         # conditional distributions of f1 and f2
-        f1_star = gp1.conditional("f1_star", X_star, X=X, y=y, noise=noise)
-        f2_star = gp2.conditional("f2_star", X_star, X=X, y=y, noise=noise)
+        f1_star = gp1.conditional("f1_star", X_star, 
+                                  given={"X": X, "y": y, "noise": noise, "gp": gp})
+        f2_star = gp2.conditional("f2_star", X_star, 
+                                  given={"X": X, "y": y, "noise": noise, "gp": gp})
 
-        # conditional of f1 + f2, additional kwargs not required
+        # conditional of f1 + f2, `given` not required
         f_star = gp.conditional("f_star", X_star)
 
+This second block produces the conditional distributions.  Notice that extra 
+arguments are required for conditionals of :math:`f1` and :math:`f2`, but not
+:math:`f`.  This is because those arguments are cached when calling 
+:code:`.marginal_likelihood` was called on :code:`gp`.
+
 .. note::
-  The additional arguments :code:`X`, :code:`y`, and :code:`noise` must be
-  provided as **keyword arguments**!
-
-The :code:`gp` object keeps track of the inputs it used when :code:`marginal_likelihood`
-or :code:`prior` was set.  Since the marginal likelihoood method of :code:`gp1` or 
-:code:`gp2` weren't called, their conditionals need to be provided with the required 
-inputs.  In the same fashion as the prior, :code:`f_star`, :code:`f1_star` and 
-:code:`f2_star` are random variables that can now be used like any other random 
-variable in PyMC3.  
+  When constructing conditionals, the additional arguments :code:`X`, :code:`y`,
+  :code:`noise` and :code:`gp` must be provided as a dict called `given`!
+
+Since the marginal likelihoood method of :code:`gp1` or :code:`gp2` weren't called, 
+their conditionals need to be provided with the required inputs.  In the same 
+fashion as the prior, :code:`f_star`, :code:`f1_star` and :code:`f2_star` are random
+variables that can now be used like any other random variable in PyMC3.  
 
 Check the notebooks for detailed demonstrations of the usage of GP functionality
 in PyMC3.