Expand documentation (#3164)

* Clarify that backends need model context.

* Rewrite Bound docstring.

* Modify tutorial intro to Bound.

Author: rpgoldman

docs/source/api/bounds.rst

@@ -6,6 +6,10 @@ PyMC3 includes the construct :class:`~pymc3.distributions.bound.Bound` for
 placing constraints on existing probability distributions.  It modifies a given
 distribution to take values only within a specified interval.
 
+Note that the `Bound` class does *not* directly create a bounded
+distribution: instead it creates a Callable class that can be
+*invoked* to create a bounded distribution, as the example below illustrates.
+
 Some types of variables require constraints.  For instance, it doesn't make
 sense for a standard deviation to have a negative value, so something like a
 Normal prior on a parameter that represents a standard deviation would be
@@ -43,6 +47,14 @@ cleaner notationally to define both the bound and variable together. ::
     with model:
         x = pm.Bound(pm.Normal, lower=0.0)('x', mu=1.0, sd=3.0)
 
+However, it is possible to create multiple different random variables
+that have the same bound applied to them::
+
+    with model:
+        BoundNormal = pm.Bound(pm.Normal, lower=0.0)
+        hyper_mu = BoundNormal("hyper_mu", mu=1, sd=0.5)
+        mu = BoundNormal("mu", mu=hyper_mu, sd=1)
+
 Bounds can also be applied to a vector of random variables.  With the same
 ``BoundedNormal`` object we created previously we can write::
 

pymc3/backends/__init__.py

@@ -20,8 +20,12 @@
 in the directory 'test'.
 
     >>> import pymc3 as pm
-    >>> db = pm.backends.Text('test')
-    >>> trace = pm.sample(..., trace=db)
+    >>> with pm.Model():
+    >>>      db = pm.backends.Text('test')
+    >>>      trace = pm.sample(..., trace=db)
+
+Note that as in the example above, one must have an active model context,
+or pass a `model` parameter in order to create a backend.
 
 Selecting values from a backend
 -------------------------------

pymc3/distributions/bound.py

@@ -157,7 +157,8 @@ def __init__(self, distribution, lower, upper,
 
 class Bound(object):
     R"""
-    Create a new upper, lower or upper+lower bounded distribution.
+    Create a Bound variable object that can be applied to create
+    a new upper, lower, or upper and lower bounded distribution.
 
     The resulting distribution is not normalized anymore. This
     is usually fine if the bounds are constants. If you need
@@ -181,9 +182,13 @@ class Bound(object):
 
         with pm.Model():
             NegativeNormal = pm.Bound(pm.Normal, upper=0.0)
-            par1 = NegativeNormal('par2', mu=0.0, sd=1.0, testval=1.0)
+            par1 = NegativeNormal('par`', mu=0.0, sd=1.0, testval=-0.5)
+            # you can use the Bound object multiple times to
+            # create multiple bounded random variables
+            par1_1 = NegativeNormal('par1_1', mu=-1.0, sd=1.0, testval=-1.5)
 
-            # or you can define it implicitly within the model context
+            # you can also define a Bound implicitly, while applying
+            # it to a random variable
             par2 = pm.Bound(pm.Normal, lower=-1.0, upper=1.0)(
                     'par2', mu=0.0, sd=1.0, testval=1.0)
     """