Transformations

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 log transform but in some cases it may be advantageous to use the 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 ordered in mixture models.

   • NB: ordered is not guaranteed to work correctly when used in combination with other transforms, such as simplex and ZeroSumTransform.

Warning

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

• Transforms are not applied during forward sampling, i.e. pymc.draw(), pymc.sample_prior_predictive() and pymc.sample_posterior_predictive()

• Transforms are not applied when sampling observed random variables with pymc.sample()

Since transforms are not applied during pymc.sample_prior_predictive(), a workaround to carry out prior predictive checks is to remove observations from the likelihood and use 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 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.

circular	Instantiation of pymc.logprob.transforms.CircularTransform for use in the transform argument of a random variable.
log	Instantiation of pymc.logprob.transforms.LogTransform for use in the transform argument of a random variable.
log_exp_m1	Instantiation of pymc.distributions.transforms.LogExpM1 for use in the transform argument of a random variable.
logodds	Instantiation of pymc.logprob.transforms.LogOddsTransform for use in the transform argument of a random variable.
ordered	Instantiation of pymc.distributions.transforms.Ordered for use in the transform argument of a random variable.
simplex	Instantiation of pymc.logprob.transforms.SimplexTransform for use in the transform argument of a random variable.

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.

CholeskyCovPacked(n)	Transforms the diagonal elements of the LKJCholeskyCov distribution to be on the log scale
CircularTransform()
Interval([lower, upper, bounds_fn])	Wrapper around pymc.logprob.transforms.IntervalTransform for use in the transform argument of a random variable.
LogExpM1()
LogOddsTransform()
LogTransform()
Ordered([ndim_supp])
SimplexTransform()
ZeroSumTransform(zerosum_axes)	Constrains any random samples to sum to zero along the user-provided zerosum_axes.

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 Chain transform that applies the user-provided transform on top of the default one.

Chain

alias of ChainedTransform