|
| 1 | +================= |
| 2 | +Bounded Variables |
| 3 | +================= |
| 4 | + |
| 5 | +PyMC3 includes the construct ``Bound`` for placing constraints on existing |
| 6 | +probability distributions. It modifies a given distribution to take values |
| 7 | +only within a specified interval. |
| 8 | + |
| 9 | +Some types of variables require constraints. For instance, it doesn't make |
| 10 | +sense for a standard deviation to have a negative value, so something like a |
| 11 | +Normal prior on a parameter that represents a standard deviation would be |
| 12 | +inappropriate. PyMC3 includes distributions that have positive support, such |
| 13 | +as ``Gamma`` or ``Exponential``. PyMC3 also includes several bounded |
| 14 | +distributions, such as ``Uniform``, ``HalfNormal``, and ``HalfCauchy``, that |
| 15 | +are restricted to a specific domain. |
| 16 | + |
| 17 | +All univariate distributions in PyMC3 can be given bounds. The distribution of |
| 18 | +a continuous variable that has been bounded is automatically transformed into |
| 19 | +an unnormalized distribution whose domain is unconstrained. The transformation |
| 20 | +improves the efficiency of sampling and variational inference algorithms. |
| 21 | + |
| 22 | +Usage |
| 23 | +##### |
| 24 | + |
| 25 | +For example, one may have prior information that suggests that the value of a |
| 26 | +parameter representing a standard deviation is near one. One could use a |
| 27 | +Normal distribution while constraining the support to be positive. The |
| 28 | +specification of a bounded distribution should go within the model block:: |
| 29 | + |
| 30 | + import pymc3 as pm |
| 31 | + |
| 32 | + with pm.Model() as model: |
| 33 | + BoundedNormal = pm.Bound(pm.Normal, lower=0.0) |
| 34 | + x = BoundedNormal('x', mu=1.0, sd=3.0) |
| 35 | + |
| 36 | +If the bound will be applied to a single variable in the model, it may be |
| 37 | +cleaner notationally to define both the bound and variable together. :: |
| 38 | + |
| 39 | + with model: |
| 40 | + x = pm.Bound(pm.Normal, lower=0.0)('x', mu=1.0, sd=3.0) |
| 41 | + |
| 42 | +Bounds can also be applied to a vector of random variables. With the same |
| 43 | +``BoundedNormal`` object we created previously we can write:: |
| 44 | + |
| 45 | + with model: |
| 46 | + x_vector = BoundedNormal('x_vector', mu=1.0, sd=3.0, shape=3) |
| 47 | + |
| 48 | +Caveats |
| 49 | +####### |
| 50 | + |
| 51 | +* Bounds cannot be given to variables that are ``observed``. To model |
| 52 | + truncated data, use a ``Potential`` in combination with a cumulative |
| 53 | + probability function. See `this example <https://github.com/pymc-devs/pymc3/blob/master/pymc3/examples/censored_data.py>`_. |
| 54 | + |
| 55 | +* The automatic transformation applied to continuous distributions results in |
| 56 | + an unnormalized probability distribution. This doesn't effect inference |
| 57 | + algorithms but may complicate some model comparison procedures. |
| 58 | + |
0 commit comments