Adds documentation for Bound'ed variables (#2391)

* add doc for bounded variables

* adds Usage, Caveats sections, fixes in response to comments

* remove example definition of boundeddist from outside context

* clarification of vector

* moved to source/api/ and added to api.rst

Author: bwengals

docs/source/api.rst

@@ -8,6 +8,7 @@ API Reference
    :maxdepth: 2
 
    api/distributions
+   api/bounds
    api/inference
    api/glm
    api/gp
@@ -16,4 +17,4 @@ API Reference
    api/diagnostics
    api/backends
    api/math
-   api/data
+   api/data

docs/source/api/bounds.rst

@@ -0,0 +1,58 @@
+=================
+Bounded Variables
+=================
+
+PyMC3 includes the construct ``Bound`` for placing constraints on existing
+probability distributions.  It modifies a given distribution to take values
+only within a specified interval.  
+
+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
+inappropriate.  PyMC3 includes distributions that have positive support, such
+as ``Gamma`` or ``Exponential``.  PyMC3 also includes several bounded
+distributions, such as ``Uniform``, ``HalfNormal``, and ``HalfCauchy``, that
+are restricted to a specific domain.  
+
+All univariate distributions in PyMC3 can be given bounds.  The distribution of
+a continuous variable that has been bounded is automatically transformed into
+an unnormalized distribution whose domain is unconstrained.  The transformation
+improves the efficiency of sampling and variational inference algorithms.
+
+Usage
+#####
+
+For example, one may have prior information that suggests that the value of a
+parameter representing a standard deviation is near one.  One could use a
+Normal distribution while constraining the support to be positive.  The
+specification of a bounded distribution should go within the model block::
+
+    import pymc3 as pm
+
+    with pm.Model() as model:
+        BoundedNormal = pm.Bound(pm.Normal, lower=0.0)
+        x = BoundedNormal('x', mu=1.0, sd=3.0)
+        
+If the bound will be applied to a single variable in the model, it may be
+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)
+
+Bounds can also be applied to a vector of random variables.  With the same
+``BoundedNormal`` object we created previously we can write::
+
+    with model: 
+        x_vector = BoundedNormal('x_vector', mu=1.0, sd=3.0, shape=3)
+
+Caveats
+#######
+
+* Bounds cannot be given to variables that are ``observed``.  To model
+  truncated data, use a ``Potential`` in combination with a cumulative
+  probability function.  See `this example <https://github.com/pymc-devs/pymc3/blob/master/pymc3/examples/censored_data.py>`_.
+
+* The automatic transformation applied to continuous distributions results in
+  an unnormalized probability distribution.  This doesn't effect inference
+  algorithms but may complicate some model comparison procedures.
+

pymc3/distributions/bound.py

@@ -176,17 +176,13 @@ class Bound(object):
 
     Example
     -------
-    # Bounded distribution can be defined before the model context
-    PositiveNormal = pm.Bound(pm.Normal, lower=0.0)
     with pm.Model():
-        par1 = PositiveNormal('par1', mu=0.0, sd=1.0, testval=1.0)
-        # or within the model context
         NegativeNormal = pm.Bound(pm.Normal, upper=0.0)
-        par2 = NegativeNormal('par2', mu=0.0, sd=1.0, testval=1.0)
+        par1 = NegativeNormal('par2', mu=0.0, sd=1.0, testval=1.0)
 
         # or you can define it implicitly within the model context
-        par3 = pm.Bound(pm.Normal, lower=-1.0, upper=1.0)(
-                'par3', mu=0.0, sd=1.0, testval=1.0)
+        par2 = pm.Bound(pm.Normal, lower=-1.0, upper=1.0)(
+                'par2', mu=0.0, sd=1.0, testval=1.0)
     """
 
     def __init__(self, distribution, lower=None, upper=None):