Doc Improvements: Bound API doc, HalfNormal description, markup fixes (#2888)

* Include API reference for Bound class

* Include API reference for Bound class
* In documentation for bounds, link to distributions

* Fix mean and variance of HalfNormal in docs

* Add missing sphinx markup for kronecker/math

* Fix external link in docs notebook

* Add encoding declaration in distribution.py

* Change URL to https

* Fix markup for MatrixNormal

Author: HolgerPeters

docs/source/api/bounds.rst

@@ -2,17 +2,21 @@
 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.  
+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.
 
 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.  
+as :class:`~pymc3.distributions.continuous.Gamma` or
+:class:`~pymc3.distributions.continuous.Exponential`.  PyMC3 also includes
+several bounded distributions, such as
+:class:`~pymc3.distributions.continuous.Uniform`,
+:class:`~pymc3.distributions.continuous.HalfNormal`, and
+:class:`~pymc3.distributions.continuous.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
@@ -32,7 +36,7 @@ specification of a bounded distribution should go within the model block::
     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. ::
 
@@ -42,17 +46,24 @@ cleaner notationally to define both the bound and variable together. ::
 Bounds can also be applied to a vector of random variables.  With the same
 ``BoundedNormal`` object we created previously we can write::
 
-    with model: 
+    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
+  truncated data, use a :func:`~pymc3.model.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.
 
+API
+###
+
+
+.. currentmodule:: pymc3.distributions.bound
+.. automodule:: pymc3.distributions.bound
+   :members:

docs/source/notebooks/bayesian_neural_network_with_sgfs.ipynb

@@ -16,7 +16,7 @@
    "source": [
     "## Stochastic Gradient Fisher Scoring\n",
     "\n",
-    "Author: [__shkr__](www.github.com/shkr)\n",
+    "Author: [__shkr__](https://www.github.com/shkr)\n",
     "\n",
     "```\n",
     "Can we approximately sample from a Bayesian posterior distribution if we are only allowed to touch a small mini-batch of data-items for every sample we generate?\n",

pymc3/distributions/bound.py

@@ -161,7 +161,7 @@ class Bound(object):
     The resulting distribution is not normalized anymore. This
     is usually fine if the bounds are constants. If you need
     truncated distributions, use `Bound` in combination with
-    a `pm.Potential` with the cumulative probability function.
+    a :class:`~pymc3.model.Potential` with the cumulative probability function.
 
     The bounds are inclusive for discrete distributions.
 

pymc3/distributions/continuous.py

@@ -336,7 +336,19 @@ class HalfNormal(PositiveContinuous):
 
        f(x \mid \tau) =
            \sqrt{\frac{2\tau}{\pi}}
-           \exp\left\{ {\frac{-x^2 \tau}{2}}\right\}
+           \exp\left(\frac{-x^2 \tau}{2}\right)
+
+       f(x \mid \sigma) =\sigma
+           \sqrt{\frac{2}{\pi}}
+           \exp\left(\frac{-x^2}{2\sigma^2}\right)
+
+    .. note::
+
+       The parameters ``sigma``/``tau`` (:math:`\sigma`/:math:`\tau`) refer to
+       the standard deviation/precision of the unfolded normal distribution, for
+       the standard deviation of the half-normal distribution, see below. For
+       the half-normal, they are just two parameterisation :math:`\sigma^2
+       \equiv \frac{1}{\tau}` of a scale parameter
 
     .. plot::
 
@@ -355,24 +367,24 @@ class HalfNormal(PositiveContinuous):
 
     ========  ==========================================
     Support   :math:`x \in [0, \infty)`
-    Mean      :math:`0`
-    Variance  :math:`\dfrac{1}{\tau}` or :math:`\sigma^2`
+    Mean      :math:`\sqrt{\dfrac{2}{\tau \pi}}` or :math:`\dfrac{\sigma \sqrt{2}}{\sqrt{\pi}}`
+    Variance  :math:`\dfrac{1}{\tau}\left(1 - \dfrac{2}{\pi}\right)` or :math:`\sigma^2\left(1 - \dfrac{2}{\pi}\right)`
     ========  ==========================================
 
     Parameters
     ----------
     sd : float
-        Standard deviation (sd > 0) (only required if tau is not specified).
+        Scale parameter :math:`sigma` (``sd`` > 0) (only required if ``tau`` is not specified).
     tau : float
-        Precision (tau > 0) (only required if sd is not specified).
-        
+        Precision :math:`tau` (tau > 0) (only required if sd is not specified).
+
     Examples
     --------
     .. code-block:: python
 
         with pm.Model():
             x = pm.HalfNormal('x', sd=10)
-        
+
         with pm.Model():
             x = pm.HalfNormal('x', tau=1/15)
     """

pymc3/distributions/multivariate.py

@@ -1151,7 +1151,8 @@ class MatrixNormal(Continuous):
     properties for inversion. For example, if draws from MvNormal had the same
     covariance structure, but were scaled by different powers of an unknown
     constant, both the covariance and scaling could be learned as follows
-    (see the docstring of `LKJCholeskyCov` for more information about this)::
+    (see the docstring of `LKJCholeskyCov` for more information about this)
+
     .. code:: python
 
         # Setup data

pymc3/math.py

@@ -25,7 +25,7 @@
 
 def kronecker(*Ks):
     """Return the Kronecker product of arguments:
-            K_1 \otimes K_2 \otimes ... \otimes K_D
+          :math:`K_1 \otimes K_2 \otimes ... \otimes K_D`
 
     Parameters
     ----------
@@ -47,7 +47,7 @@ def cartesian(*arrays):
 
 
 def kron_matrix_op(krons, m, op):
-    """Apply op to krons and m in a way that reproduces op(kronecker(*krons), m)
+    """Apply op to krons and m in a way that reproduces ``op(kronecker(*krons), m)``
 
     Parameters
     -----------