tfp.distributions.TransformedDistribution

A Transformed Distribution.

Inherits From: Distribution

tfp.distributions.TransformedDistribution(
    distribution, bijector, kwargs_split_fn=_default_kwargs_split_fn,
    validate_args=False, parameters=None, name=None
)

Used in the notebooks

Used in the tutorials
Approximate inference for STS models with non-Gaussian observations

A TransformedDistribution models p(y) given a base distribution p(x), and a deterministic, invertible, differentiable transform, Y = g(X). The transform is typically an instance of the Bijector class and the base distribution is typically an instance of the Distribution class.

A Bijector is expected to implement the following functions:

forward,
inverse,
inverse_log_det_jacobian.

The semantics of these functions are outlined in the Bijector documentation.

We now describe how a TransformedDistribution alters the input/outputs of a Distribution associated with a random variable (rv) X.

Write cdf(Y=y) for an absolutely continuous cumulative distribution function of random variable Y; write the probability density function pdf(Y=y) := d^k / (dy_1,...,dy_k) cdf(Y=y) for its derivative wrt to Y evaluated at y. Assume that Y = g(X) where g is a deterministic diffeomorphism, i.e., a non-random, continuous, differentiable, and invertible function. Write the inverse of g as X = g^{-1}(Y) and (J o g)(x) for the Jacobian of g evaluated at x.

A TransformedDistribution implements the following operations:

sample Mathematically: Y = g(X) Programmatically: bijector.forward(distribution.sample(...))
log_prob Mathematically: `(log o pdf)(Y=y) = (log o pdf o g^{-1})(y)
```
               + (log o abs o det o J o g^{-1})(y)`
```
Programmatically: (distribution.log_prob(bijector.inverse(y)) + bijector.inverse_log_det_jacobian(y))
log_cdf Mathematically: (log o cdf)(Y=y) = (log o cdf o g^{-1})(y) Programmatically: distribution.log_cdf(bijector.inverse(x))
and similarly for: cdf, prob, log_survival_function, survival_function.

Kullback-Leibler divergence is also well defined for TransformedDistribution instances that have matching bijectors. Bijector matching is performed via the Bijector.eq method, e.g., td1.bijector == td2.bijector, as part of the KL calculation. If the underlying bijectors do not match, a NotImplementedError is raised when calling kl_divergence. This is the same behavior as calling kl_divergence when two distributions do not have a registered KL divergence.

A simple example constructing a Log-Normal distribution from a Normal distribution:

tfd = tfp.distributions
tfb = tfp.bijectors
log_normal = tfd.TransformedDistribution(
  distribution=tfd.Normal(loc=0., scale=1.),
  bijector=tfb.Exp(),
  name='LogNormalTransformedDistribution')

A LogNormal made from callables:

tfd = tfp.distributions
tfb = tfp.bijectors
log_normal = tfd.TransformedDistribution(
  distribution=tfd.Normal(loc=0., scale=1.),
  bijector=tfb.Inline(
    forward_fn=tf.exp,
    inverse_fn=tf.log,
    inverse_log_det_jacobian_fn=(
      lambda y: -tf.reduce_sum(tf.log(y), axis=-1)),
  name='LogNormalTransformedDistribution')

Another example constructing a Normal from a StandardNormal:

tfd = tfp.distributions
tfb = tfp.bijectors
normal = tfd.TransformedDistribution(
  distribution=tfd.Normal(loc=0., scale=1.),
  bijector=tfb.Shift(shift=-1.)(tfb.Scale(scale=2.)),
  name='NormalTransformedDistribution')

A TransformedDistribution's batch_shape is the same as that of the base distribution, and its event_shape is the forward_event_shape of the bijector applied to the event_shape of the base distribution.

tfd.Sample or tfd.Independent may be used to add extra IID dimensions to the event_shape of the base distribution before the bijector operates on it. The following example demonstrates how to construct a multivariate Normal as a TransformedDistribution, by adding a rank-1 IID dimension to the event_shape of a standard Normal and applying tfb.ScaleMatvecTriL.

tfd = tfp.distributions
tfb = tfp.bijectors
# We will create two MVNs with batch_shape = event_shape = 2.
mean = [[-1., 0],      # batch:0
        [0., 1]]       # batch:1
chol_cov = [[[1., 0],
             [0, 1]],  # batch:0
            [[1, 0],
             [2, 2]]]  # batch:1
mvn1 = tfd.TransformedDistribution(
    distribution=tfd.Sample(
        tfd.Normal(loc=[0., 0], scale=1.),  # base_dist.batch_shape == [2]
        sample_shape=[2])                   # base_dist.event_shape == [2]
    bijector=tfb.Shift(shift=mean)(tfb.ScaleMatvecTriL(scale_tril=chol_cov)))
mvn2 = ds.MultivariateNormalTriL(loc=mean, scale_tril=chol_cov)
# mvn1.log_prob(x) == mvn2.log_prob(x)

<!-- Tabular view -->
 <table class="responsive fixed orange">
<colgroup><col width="214px"><col></colgroup>
<tr><th colspan="2"><h2 class="add-link">Args</h2></th></tr>

<tr>
<td>
`distribution`
</td>
<td>
The base distribution instance to transform. Typically an
instance of `Distribution`.
</td>
</tr><tr>
<td>
`bijector`
</td>
<td>
The object responsible for calculating the transformation.
Typically an instance of `Bijector`.
</td>
</tr><tr>
<td>
`kwargs_split_fn`
</td>
<td>
Python `callable` which takes a kwargs `dict` and returns
a tuple of kwargs `dict`s for each of the `distribution` and `bijector`
parameters respectively.
Default value: `_default_kwargs_split_fn` (i.e.,
`lambda kwargs: (kwargs.get('distribution_kwargs', {}),
kwargs.get('bijector_kwargs', {}))`)
</td>
</tr><tr>
<td>
`validate_args`
</td>
<td>
Python `bool`, default `False`. When `True` distribution
parameters are checked for validity despite possibly degrading runtime
performance. When `False` invalid inputs may silently render incorrect
outputs.
</td>
</tr><tr>
<td>
`parameters`
</td>
<td>
Locals dict captured by subclass constructor, to be used for
copy/slice re-instantiation operations.
</td>
</tr><tr>
<td>
`name`
</td>
<td>
Python `str` name prefixed to Ops created by this class. Default:
`bijector.name + distribution.name`.
</td>
</tr>
</table>





<!-- Tabular view -->
 <table class="responsive fixed orange">
<colgroup><col width="214px"><col></colgroup>
<tr><th colspan="2"><h2 class="add-link">Attributes</h2></th></tr>

<tr>
<td>
`allow_nan_stats`
</td>
<td>
Python `bool` describing behavior when a stat is undefined.

Stats return +/- infinity when it makes sense. E.g., the variance of a
Cauchy distribution is infinity. However, sometimes the statistic is
undefined, e.g., if a distribution's pdf does not achieve a maximum within
the support of the distribution, the mode is undefined. If the mean is
undefined, then by definition the variance is undefined. E.g. the mean for
Student's T for df = 1 is undefined (no clear way to say it is either + or -
infinity), so the variance = E[(X - mean)**2] is also undefined.
</td>
</tr><tr>
<td>
`batch_shape`
</td>
<td>
Shape of a single sample from a single event index as a `TensorShape`.

May be partially defined or unknown.

The batch dimensions are indexes into independent, non-identical
parameterizations of this distribution.
</td>
</tr><tr>
<td>
`bijector`
</td>
<td>
Function transforming x => y.
</td>
</tr><tr>
<td>
`distribution`
</td>
<td>
Base distribution, p(x).
</td>
</tr><tr>
<td>
`dtype`
</td>
<td>
The `DType` of `Tensor`s handled by this `Distribution`.
</td>
</tr><tr>
<td>
`event_shape`
</td>
<td>
Shape of a single sample from a single batch as a `TensorShape`.

May be partially defined or unknown.
</td>
</tr><tr>
<td>
`name`
</td>
<td>
Name prepended to all ops created by this `Distribution`.
</td>
</tr><tr>
<td>
`name_scope`
</td>
<td>
Returns a `tf.name_scope` instance for this class.
</td>
</tr><tr>
<td>
`parameters`
</td>
<td>
Dictionary of parameters used to instantiate this `Distribution`.
</td>
</tr><tr>
<td>
`reparameterization_type`
</td>
<td>
Describes how samples from the distribution are reparameterized.

Currently this is one of the static instances
`tfd.FULLY_REPARAMETERIZED` or `tfd.NOT_REPARAMETERIZED`.
</td>
</tr><tr>
<td>
`submodules`
</td>
<td>
Sequence of all sub-modules.

Submodules are modules which are properties of this module, or found as
properties of modules which are properties of this module (and so on).

<pre class="devsite-click-to-copy prettyprint lang-py">
<code class="devsite-terminal" data-terminal-prefix="&gt;&gt;&gt;">a = tf.Module()</code>
<code class="devsite-terminal" data-terminal-prefix="&gt;&gt;&gt;">b = tf.Module()</code>
<code class="devsite-terminal" data-terminal-prefix="&gt;&gt;&gt;">c = tf.Module()</code>
<code class="devsite-terminal" data-terminal-prefix="&gt;&gt;&gt;">a.b = b</code>
<code class="devsite-terminal" data-terminal-prefix="&gt;&gt;&gt;">b.c = c</code>
<code class="devsite-terminal" data-terminal-prefix="&gt;&gt;&gt;">list(a.submodules) == [b, c]</code>
<code class="no-select nocode">True</code>
<code class="devsite-terminal" data-terminal-prefix="&gt;&gt;&gt;">list(b.submodules) == [c]</code>
<code class="no-select nocode">True</code>
<code class="devsite-terminal" data-terminal-prefix="&gt;&gt;&gt;">list(c.submodules) == []</code>
<code class="no-select nocode">True</code>
</pre>

</td>
</tr><tr>
<td>
`trainable_variables`
</td>
<td>
Sequence of trainable variables owned by this module and its submodules.

Note: this method uses reflection to find variables on the current instance
and submodules. For performance reasons you may wish to cache the result
of calling this method if you don't expect the return value to change.
</td>
</tr><tr>
<td>
`validate_args`
</td>
<td>
Python `bool` indicating possibly expensive checks are enabled.
</td>
</tr><tr>
<td>
`variables`
</td>
<td>
Sequence of variables owned by this module and its submodules.

Note: this method uses reflection to find variables on the current instance
and submodules. For performance reasons you may wish to cache the result
of calling this method if you don't expect the return value to change.
</td>
</tr>
</table>



## Methods

<h3 id="batch_shape_tensor"><code>batch_shape_tensor</code></h3>

<a target="_blank" href="https://github.com/tensorflow/probability/blob/v0.12.1/tensorflow_probability/python/distributions/distribution.py#L825-L863">View source</a>

<pre class="devsite-click-to-copy prettyprint lang-py tfo-signature-link">
<code>batch_shape_tensor(
    name=&#x27;batch_shape_tensor&#x27;
)
</code></pre>

Shape of a single sample from a single event index as a 1-D `Tensor`.

The batch dimensions are indexes into independent, non-identical
parameterizations of this distribution.

<!-- Tabular view -->
 <table class="responsive fixed orange">
<colgroup><col width="214px"><col></colgroup>
<tr><th colspan="2">Args</th></tr>

<tr>
<td>
`name`
</td>
<td>
name to give to the op
</td>
</tr>
</table>



<!-- Tabular view -->
 <table class="responsive fixed orange">
<colgroup><col width="214px"><col></colgroup>
<tr><th colspan="2">Returns</th></tr>

<tr>
<td>
`batch_shape`
</td>
<td>
`Tensor`.
</td>
</tr>
</table>



<h3 id="cdf"><code>cdf</code></h3>

<a target="_blank" href="https://github.com/tensorflow/probability/blob/v0.12.1/tensorflow_probability/python/distributions/distribution.py#L1112-L1130">View source</a>

<pre class="devsite-click-to-copy prettyprint lang-py tfo-signature-link">
<code>cdf(
    value, name=&#x27;cdf&#x27;, **kwargs
)
</code></pre>

Cumulative distribution function.

Given random variable `X`, the cumulative distribution function `cdf` is:

```none
cdf(x) := P[X <= x]

Args
`value`	`float` or `double` `Tensor`.
`name`	Python `str` prepended to names of ops created by this function.
`**kwargs`	Named arguments forwarded to subclass implementation.

Returns
`cdf`	a `Tensor` of shape `sample_shape(x) + self.batch_shape` with values of type `self.dtype`.

Args
`other`	`tfp.distributions.Distribution` instance.
`name`	Python `str` prepended to names of ops created by this function.

Args
`*args`	Passed to implementation `_default_event_space_bijector`.
`**kwargs`	Passed to implementation `_default_event_space_bijector`.

Args
`sample_shape`	`Tensor` or python list/tuple. Desired shape of a call to `sample()`.
`name`	name to prepend ops with.

Args
`dtype`	Optional float `dtype` to assume for continuous-valued parameters. Some constraining bijectors require advance knowledge of the dtype because certain constants (e.g., `tfb.Softplus.low`) must be instantiated with the same dtype as the values to be transformed.
`num_classes`	Optional `int` `Tensor` number of classes to assume when inferring the shape of parameters for categorical-like distributions. Otherwise ignored.

Args
`sample_shape`	0D or 1D `int32` `Tensor`. Shape of the generated samples.
`seed`	Python integer or `tfp.util.SeedStream` instance, for seeding PRNG.
`name`	name to give to the op.
`**kwargs`	Named arguments forwarded to subclass implementation.

tfp.distributions.TransformedDistribution

Used in the notebooks

copy

covariance

cross_entropy

entropy

event_shape_tensor

experimental_default_event_space_bijector

is_scalar_batch

is_scalar_event

kl_divergence

log_cdf

log_prob

log_survival_function

mean

mode

param_shapes

param_static_shapes

parameter_properties

prob

quantile

sample

stddev

survival_function

variance

with_name_scope

__getitem__

__iter__

`copy`

`covariance`

`cross_entropy`

`entropy`

`event_shape_tensor`

`experimental_default_event_space_bijector`

`is_scalar_batch`

`is_scalar_event`

`kl_divergence`

`log_cdf`

`log_prob`

`log_survival_function`

`mean`

`mode`

`param_shapes`

`param_static_shapes`

`parameter_properties`

`prob`

`quantile`

`sample`

`stddev`

`survival_function`

`variance`

`with_name_scope`

`getitem`

`iter`