# Transformations of a random variable from one space to another.¶

Note that for convenience these entities can be addressed as pm.transforms.X for any name X, although they are actually implemented as pm.distributions.transforms.*X*.

## Transform Instances¶

Transform instances are the entities that should be used in the transform parameter to a random variable constructor. These are initialized instances of the Transform Classes, which are described below.

stick_breaking

Instantiation of StickBreaking Transform class for use in the transform argument of a random variable.

logodds

Instantiation of LogOdds Transform class for use in the transform argument of a random variable.

interval

Alias of Interval Transform class for use in the transform argument of a random variable.

log_exp_m1

Instantiation of LogExpM1 Transform class for use in the transform argument of a random variable.

lowerbound

Alias of LowerBound Transform class for use in the transform argument of a random variable.

upperbound

Alias of UpperBound Transform class for use in the transform argument of a random variable.

ordered

Instantiation of Ordered Transform class for use in the transform argument of a random variable.

log

Instantiation of Log Transform class for use in the transform argument of a random variable.

sum_to_1

Instantiation of SumTo1 Transform class for use in the transform argument of a random variable.

circular

Instantiation of Circular Transform class for use in the transform argument of a random variable.

pymc3.distributions.transforms.t_stick_breaking(eps: float) → pymc3.distributions.transforms.StickBreaking

Return a new StickBreaking transform with specified eps(ilon), instead of the default.

## Transform Base Classes¶

Typically the programmer will not use these directly.

class pymc3.distributions.transforms.Transform

A transformation of a random variable from one space into another.

Attributes
name: str
backward(self, z)

Applies inverse of transformation to input variable z. When transform is used on some distribution p, which has observed values z, it is used to transform the values of z correctly to the support of p.

Parameters
z: tensor

Input tensor to be inverse transformed.

Returns
tensor

Inverse transformed tensor.

forward(self, x)

Applies transformation forward to input variable x. When transform is used on some distribution p, it will transform the random variable x after sampling from p.

Parameters
x: tensor

Input tensor to be transformed.

Returns
tensor

Transformed tensor.

forward_val(self, x, point)

Applies transformation forward to input array x. Similar to forward but for constant data.

Parameters
x: array_like

Input array to be transformed.

point: array_like, optional

Test value used to draw (fix) bounds-like transformations

Returns
array_like

Transformed array.

jacobian_det(self, x)

Calculates logarithm of the absolute value of the Jacobian determinant for input x.

Parameters
x: tensor

Input to calculate Jacobian determinant of.

Returns
tensor

The log abs Jacobian determinant of x w.r.t. this transform.

pymc3.distributions.transforms.transform
class pymc3.distributions.transforms.TransformedDistribution(dist, transform, *args, **kwargs)

A distribution that has been transformed from one space into another.

Parameters
dist: Distribution
transform: Transform
args, kwargs

arguments to Distribution

logp(self, x)

Calculate log-probability of Transformed distribution at specified value.

Parameters
x: numeric

Value for which log-probability is calculated.

Returns
TensorVariable
logp_nojac(self, x)

Calculate log-probability of Transformed distribution at specified value without jacobian term for transforms.

Parameters
x: numeric

Value for which log-probability is calculated.

Returns
TensorVariable

## Transform Composition Classes¶

class pymc3.distributions.transforms.Chain(transform_list)
backward(self, y)

Applies inverse of transformation to input variable z. When transform is used on some distribution p, which has observed values z, it is used to transform the values of z correctly to the support of p.

Parameters
z: tensor

Input tensor to be inverse transformed.

Returns
tensor

Inverse transformed tensor.

forward(self, x)

Applies transformation forward to input variable x. When transform is used on some distribution p, it will transform the random variable x after sampling from p.

Parameters
x: tensor

Input tensor to be transformed.

Returns
tensor

Transformed tensor.

forward_val(self, x, point=None)

Applies transformation forward to input array x. Similar to forward but for constant data.

Parameters
x: array_like

Input array to be transformed.

point: array_like, optional

Test value used to draw (fix) bounds-like transformations

Returns
array_like

Transformed array.

jacobian_det(self, y)

Calculates logarithm of the absolute value of the Jacobian determinant for input x.

Parameters
x: tensor

Input to calculate Jacobian determinant of.

Returns
tensor

The log abs Jacobian determinant of x w.r.t. this transform.

class pymc3.distributions.transforms.CholeskyCovPacked(n)
backward(self, x)

Applies inverse of transformation to input variable z. When transform is used on some distribution p, which has observed values z, it is used to transform the values of z correctly to the support of p.

Parameters
z: tensor

Input tensor to be inverse transformed.

Returns
tensor

Inverse transformed tensor.

forward(self, y)

Applies transformation forward to input variable x. When transform is used on some distribution p, it will transform the random variable x after sampling from p.

Parameters
x: tensor

Input tensor to be transformed.

Returns
tensor

Transformed tensor.

forward_val(self, y, point=None)

Applies transformation forward to input array x. Similar to forward but for constant data.

Parameters
x: array_like

Input array to be transformed.

point: array_like, optional

Test value used to draw (fix) bounds-like transformations

Returns
array_like

Transformed array.

jacobian_det(self, y)

Calculates logarithm of the absolute value of the Jacobian determinant for input x.

Parameters
x: tensor

Input to calculate Jacobian determinant of.

Returns
tensor

The log abs Jacobian determinant of x w.r.t. this transform.

## Specific Transform Classes¶

class pymc3.distributions.transforms.Log
backward(self, x)

Applies inverse of transformation to input variable z. When transform is used on some distribution p, which has observed values z, it is used to transform the values of z correctly to the support of p.

Parameters
z: tensor

Input tensor to be inverse transformed.

Returns
tensor

Inverse transformed tensor.

forward(self, x)

Applies transformation forward to input variable x. When transform is used on some distribution p, it will transform the random variable x after sampling from p.

Parameters
x: tensor

Input tensor to be transformed.

Returns
tensor

Transformed tensor.

forward_val(self, x, point=None)

Applies transformation forward to input array x. Similar to forward but for constant data.

Parameters
x: array_like

Input array to be transformed.

point: array_like, optional

Test value used to draw (fix) bounds-like transformations

Returns
array_like

Transformed array.

jacobian_det(self, x)

Calculates logarithm of the absolute value of the Jacobian determinant for input x.

Parameters
x: tensor

Input to calculate Jacobian determinant of.

Returns
tensor

The log abs Jacobian determinant of x w.r.t. this transform.

class pymc3.distributions.transforms.LogExpM1
backward(self, x)

Applies inverse of transformation to input variable z. When transform is used on some distribution p, which has observed values z, it is used to transform the values of z correctly to the support of p.

Parameters
z: tensor

Input tensor to be inverse transformed.

Returns
tensor

Inverse transformed tensor.

forward(self, x)

Inverse operation of softplus.

y = Log(Exp(x) - 1)

= Log(1 - Exp(-x)) + x

forward_val(self, x, point=None)

Applies transformation forward to input array x. Similar to forward but for constant data.

Parameters
x: array_like

Input array to be transformed.

point: array_like, optional

Test value used to draw (fix) bounds-like transformations

Returns
array_like

Transformed array.

jacobian_det(self, x)

Calculates logarithm of the absolute value of the Jacobian determinant for input x.

Parameters
x: tensor

Input to calculate Jacobian determinant of.

Returns
tensor

The log abs Jacobian determinant of x w.r.t. this transform.

class pymc3.distributions.transforms.LogOdds
backward(self, x)

Applies inverse of transformation to input variable z. When transform is used on some distribution p, which has observed values z, it is used to transform the values of z correctly to the support of p.

Parameters
z: tensor

Input tensor to be inverse transformed.

Returns
tensor

Inverse transformed tensor.

forward(self, x)

Applies transformation forward to input variable x. When transform is used on some distribution p, it will transform the random variable x after sampling from p.

Parameters
x: tensor

Input tensor to be transformed.

Returns
tensor

Transformed tensor.

forward_val(self, x, point=None)

Applies transformation forward to input array x. Similar to forward but for constant data.

Parameters
x: array_like

Input array to be transformed.

point: array_like, optional

Test value used to draw (fix) bounds-like transformations

Returns
array_like

Transformed array.

class pymc3.distributions.transforms.Interval(a, b)

Transform from real line interval [a,b] to whole real line.

backward(self, x)

Applies inverse of transformation to input variable z. When transform is used on some distribution p, which has observed values z, it is used to transform the values of z correctly to the support of p.

Parameters
z: tensor

Input tensor to be inverse transformed.

Returns
tensor

Inverse transformed tensor.

forward(self, x)

Applies transformation forward to input variable x. When transform is used on some distribution p, it will transform the random variable x after sampling from p.

Parameters
x: tensor

Input tensor to be transformed.

Returns
tensor

Transformed tensor.

forward_val(self, x, point=None)

Applies transformation forward to input array x. Similar to forward but for constant data.

Parameters
x: array_like

Input array to be transformed.

point: array_like, optional

Test value used to draw (fix) bounds-like transformations

Returns
array_like

Transformed array.

jacobian_det(self, x)

Calculates logarithm of the absolute value of the Jacobian determinant for input x.

Parameters
x: tensor

Input to calculate Jacobian determinant of.

Returns
tensor

The log abs Jacobian determinant of x w.r.t. this transform.

class pymc3.distributions.transforms.LowerBound(a)

Transform from real line interval [a,inf] to whole real line.

backward(self, x)

Applies inverse of transformation to input variable z. When transform is used on some distribution p, which has observed values z, it is used to transform the values of z correctly to the support of p.

Parameters
z: tensor

Input tensor to be inverse transformed.

Returns
tensor

Inverse transformed tensor.

forward(self, x)

Applies transformation forward to input variable x. When transform is used on some distribution p, it will transform the random variable x after sampling from p.

Parameters
x: tensor

Input tensor to be transformed.

Returns
tensor

Transformed tensor.

forward_val(self, x, point=None)

Applies transformation forward to input array x. Similar to forward but for constant data.

Parameters
x: array_like

Input array to be transformed.

point: array_like, optional

Test value used to draw (fix) bounds-like transformations

Returns
array_like

Transformed array.

jacobian_det(self, x)

Calculates logarithm of the absolute value of the Jacobian determinant for input x.

Parameters
x: tensor

Input to calculate Jacobian determinant of.

Returns
tensor

The log abs Jacobian determinant of x w.r.t. this transform.

class pymc3.distributions.transforms.UpperBound(b)

Transform from real line interval [-inf,b] to whole real line.

backward(self, x)

Applies inverse of transformation to input variable z. When transform is used on some distribution p, which has observed values z, it is used to transform the values of z correctly to the support of p.

Parameters
z: tensor

Input tensor to be inverse transformed.

Returns
tensor

Inverse transformed tensor.

forward(self, x)

Applies transformation forward to input variable x. When transform is used on some distribution p, it will transform the random variable x after sampling from p.

Parameters
x: tensor

Input tensor to be transformed.

Returns
tensor

Transformed tensor.

forward_val(self, x, point=None)

Applies transformation forward to input array x. Similar to forward but for constant data.

Parameters
x: array_like

Input array to be transformed.

point: array_like, optional

Test value used to draw (fix) bounds-like transformations

Returns
array_like

Transformed array.

jacobian_det(self, x)

Calculates logarithm of the absolute value of the Jacobian determinant for input x.

Parameters
x: tensor

Input to calculate Jacobian determinant of.

Returns
tensor

The log abs Jacobian determinant of x w.r.t. this transform.

class pymc3.distributions.transforms.Ordered
backward(self, y)

Applies inverse of transformation to input variable z. When transform is used on some distribution p, which has observed values z, it is used to transform the values of z correctly to the support of p.

Parameters
z: tensor

Input tensor to be inverse transformed.

Returns
tensor

Inverse transformed tensor.

forward(self, x)

Applies transformation forward to input variable x. When transform is used on some distribution p, it will transform the random variable x after sampling from p.

Parameters
x: tensor

Input tensor to be transformed.

Returns
tensor

Transformed tensor.

forward_val(self, x, point=None)

Applies transformation forward to input array x. Similar to forward but for constant data.

Parameters
x: array_like

Input array to be transformed.

point: array_like, optional

Test value used to draw (fix) bounds-like transformations

Returns
array_like

Transformed array.

jacobian_det(self, y)

Calculates logarithm of the absolute value of the Jacobian determinant for input x.

Parameters
x: tensor

Input to calculate Jacobian determinant of.

Returns
tensor

The log abs Jacobian determinant of x w.r.t. this transform.

class pymc3.distributions.transforms.SumTo1

Transforms K - 1 dimensional simplex space (k values in [0,1] and that sum to 1) to a K - 1 vector of values in [0,1] This Transformation operates on the last dimension of the input tensor.

backward(self, y)

Applies inverse of transformation to input variable z. When transform is used on some distribution p, which has observed values z, it is used to transform the values of z correctly to the support of p.

Parameters
z: tensor

Input tensor to be inverse transformed.

Returns
tensor

Inverse transformed tensor.

forward(self, x)

Applies transformation forward to input variable x. When transform is used on some distribution p, it will transform the random variable x after sampling from p.

Parameters
x: tensor

Input tensor to be transformed.

Returns
tensor

Transformed tensor.

forward_val(self, x, point=None)

Applies transformation forward to input array x. Similar to forward but for constant data.

Parameters
x: array_like

Input array to be transformed.

point: array_like, optional

Test value used to draw (fix) bounds-like transformations

Returns
array_like

Transformed array.

jacobian_det(self, x)

Calculates logarithm of the absolute value of the Jacobian determinant for input x.

Parameters
x: tensor

Input to calculate Jacobian determinant of.

Returns
tensor

The log abs Jacobian determinant of x w.r.t. this transform.

class pymc3.distributions.transforms.StickBreaking(eps=2.220446049250313e-16)

Transforms K - 1 dimensional simplex space (k values in [0,1] and that sum to 1) to a K - 1 vector of real values. Primarily borrowed from the STAN implementation.

Parameters
eps: float, positive value

A small value for numerical stability in invlogit.

backward(self, y_)

Applies inverse of transformation to input variable z. When transform is used on some distribution p, which has observed values z, it is used to transform the values of z correctly to the support of p.

Parameters
z: tensor

Input tensor to be inverse transformed.

Returns
tensor

Inverse transformed tensor.

forward(self, x_)

Applies transformation forward to input variable x. When transform is used on some distribution p, it will transform the random variable x after sampling from p.

Parameters
x: tensor

Input tensor to be transformed.

Returns
tensor

Transformed tensor.

forward_val(self, x_, point=None)

Applies transformation forward to input array x. Similar to forward but for constant data.

Parameters
x: array_like

Input array to be transformed.

point: array_like, optional

Test value used to draw (fix) bounds-like transformations

Returns
array_like

Transformed array.

jacobian_det(self, y_)

Calculates logarithm of the absolute value of the Jacobian determinant for input x.

Parameters
x: tensor

Input to calculate Jacobian determinant of.

Returns
tensor

The log abs Jacobian determinant of x w.r.t. this transform.

class pymc3.distributions.transforms.Circular

Transforms a linear space into a circular one.

backward(self, y)

Applies inverse of transformation to input variable z. When transform is used on some distribution p, which has observed values z, it is used to transform the values of z correctly to the support of p.

Parameters
z: tensor

Input tensor to be inverse transformed.

Returns
tensor

Inverse transformed tensor.

forward(self, x)

Applies transformation forward to input variable x. When transform is used on some distribution p, it will transform the random variable x after sampling from p.

Parameters
x: tensor

Input tensor to be transformed.

Returns
tensor

Transformed tensor.

forward_val(self, x, point=None)

Applies transformation forward to input array x. Similar to forward but for constant data.

Parameters
x: array_like

Input array to be transformed.

point: array_like, optional

Test value used to draw (fix) bounds-like transformations

Returns
array_like

Transformed array.

jacobian_det(self, x)

Calculates logarithm of the absolute value of the Jacobian determinant for input x.

Parameters
x: tensor

Input to calculate Jacobian determinant of.

Returns
tensor

The log abs Jacobian determinant of x w.r.t. this transform.