transforms.rst

Transformations

.. currentmodule:: pymc.distributions.transforms

While many distributions are defined on constrained spaces (e.g. intervals), MCMC samplers typically perform best when sampling on the unconstrained real line; this is especially true of HMC samplers. PyMC balances this through the use of transforms. A transform instance can be passed to the constructor of a random variable to tell the sampler how to move between the underlying unconstrained space where the samples are actually drawn and the transformed space constituting the support of the random variable. Transforms are not currently implemented for discrete random variables.

All transforms have three core methods:

• forward: The map from a constrained space to the unconstrained space.
• backward: The inverse map from the unconstrained space to a constrained space.
• log_jac_det: The log of the determinant of the Jacobian of the backward map. This is used to account for the transformed random variable correctly in the posterior log-probability.

Note

Transforms are principally intended for internal use and in most cases users do not need to change them. In particular, all continuous distributions on a constrained domain that are implemented in PyMC have a default_transform that will automatically transform the random variables as required without needing any extra work from the user.

The main use-cases for setting custom transforms include the following:

1. The default_transform may need to be replaced with an alternative transform on the same constained space. For example, the default_transform for positive-valued random variables is the :class:`log` transform but in some cases it may be advantageous to use the :class:`log_exp_m1` transform instead.
2. The default_transform may be removed entirely in some cases when using non-HMC samplers.
3. Exceptionally, transforms can be used to add constraints to the model specification without modifying the default_transform. This can be done by specifying the additional transform via the transform parameter. However this should not be viewed as a default use-case and, in practice, this is mostly limited to using :class:`ordered` in mixture models.
   • NB: :class:`ordered` is not guaranteed to work correctly when used in combination with other transforms, such as :class:`simplex` and :class:`ZeroSumTransform`.

Warning

Transforms are only applied when sampling unobserved random variables with :func:`pymc.sample`. In particular:

• Transforms are not applied during forward sampling, i.e. :func:`pymc.draw`, :func:`pymc.sample_prior_predictive` and :func:`pymc.sample_posterior_predictive`
• Transforms are not applied when sampling observed random variables with :func:`pymc.sample`

Since transforms are not applied during :func:`pymc.sample_prior_predictive`, a workaround to carry out prior predictive checks is to remove observations from the likelihood and use :func:`pymc.sample` instead.

Transforms are not usually the correct tool to represent transformations that are part of the generative specification of the model. Such transformations should be included explicitly in the model, typically via :class:`pymc.Deterministic`. Doing so allows such transformed random variables to be sampled by forward samplers.

Transform Instances

Transform instances are the entities that should be used in the default_transform or transform parameters to a random variable constructor.

.. autosummary::
   :toctree: generated

    circular
    log
    log_exp_m1
    logodds
    ordered
    simplex

Specific Transform Classes

An instance of these classes needs to be created before being used in the default_transform or transform parameters to a random variable constructor.

.. autosummary::
   :toctree: generated

    CholeskyCovPacked
    CircularTransform
    Interval
    LogExpM1
    LogOddsTransform
    LogTransform
    Ordered
    SimplexTransform
    ZeroSumTransform

Transform Composition Classes

An instance of this class needs to be created from a list of transforms before being used in the transform parameter to a random variable constructor.

If a random variable has a default_transform and an additional transform is provided through the transform parameter, PyMC will automatically create an instance of the :class:`Chain` transform that applies the user-provided transform on top of the default one.

.. autosummary::
   :toctree: generated

    Chain