tfp.experimental.substrates.numpy.bijectors.CorrelationCholesky

Maps unconstrained reals to Cholesky-space correlation matrices.

Inherits From: Bijector

tfp.experimental.substrates.numpy.bijectors.CorrelationCholesky(
    validate_args=False, name='correlation_cholesky'
)

Mathematical Details

This bijector provides a change of variables from unconstrained reals to a parameterization of the CholeskyLKJ distribution. The CholeskyLKJ distribution [1] is a distribution on the set of Cholesky factors of positive definite correlation matrices. The CholeskyLKJ probability density function is obtained from the LKJ density on n x n matrices as follows:

1 = int p(A | eta) dA = int Z(eta) * det(A) ** (eta - 1) dA = int Z(eta) L_ii ** {(n - i - 1) + 2 * (eta - 1)} ^dL_ij (0 <= i < j < n)

where Z(eta) is the normalizer; the matrix L is the Cholesky factor of the correlation matrix A; and ^dL_ij denotes the wedge product (or differential) of the strictly lower triangular entries of L. The entries L_ij are constrained such that each entry lies in [-1, 1] and the norm of each row is

The norm includes the diagonal; which is not included in the wedge product. To preserve uniqueness, we further specify that the diagonal entries are positive.

The image of unconstrained reals under the CorrelationCholesky bijector is the set of correlation matrices which are positive definite. A correlation matrix can be characterized as a symmetric positive semidefinite matrix with 1s on the main diagonal.

For a lower triangular matrix L to be a valid Cholesky-factor of a positive definite correlation matrix, it is necessary and sufficient that each row of L have unit Euclidean norm [1]. To see this, observe that if L_i is the ith row of the Cholesky factor corresponding to the correlation matrix R, then the ith diagonal entry of R satisfies:

1 = R_i,i = L_i . L_i = ||L_i||^2

where '.' is the dot product of vectors and ||...|| denotes the Euclidean norm.

Furthermore, observe that R_i,j lies in the interval [-1, 1]. By the Cauchy-Schwarz inequality:

|R_i,j| = |L_i . L_j| <= ||L_i|| ||L_j|| = 1

This is a consequence of the fact that R is symmetric positive definite with 1s on the main diagonal.

We choose the mapping from x in R^{m} to R^{n^2} where m is the (n - 1)th triangular number; i.e. m = 1 + 2 + ... + (n - 1).

L_ij = x_i,j / s_i (for i < j) L_ii = 1 / s_i

where s_i = sqrt(1 + x_i,0^2 + xi,1^2 + ... + x(i,i-1)^2). We can check that the required constraints on the image are satisfied.

Examples

bijector.CorrelationCholesky().forward([2., 2., 1.])
# Result: [[ 1.        ,  0.        ,  0.        ],
           [ 0.70710678,  0.70710678,  0.        ],
           [ 0.66666667,  0.66666667,  0.33333333]]

bijector.CorrelationCholesky().inverse(
    [[ 1.        ,  0.        ,  0. ],
     [ 0.70710678,  0.70710678,  0.        ],
     [ 0.66666667,  0.66666667,  0.33333333]])
# Result: [2., 2., 1.]

References

[1] Stan Manual. Section 24.2. Cholesky LKJ Correlation Distribution. https://mc-stan.org/docs/2_18/functions-reference/cholesky-lkj-correlation-distribution.html [2] Daniel Lewandowski, Dorota Kurowicka, and Harry Joe, "Generating random correlation matrices based on vines and extended onion method," Journal of Multivariate Analysis 100 (2009), pp 1989-2001.

Args
`graph_parents`	Python list of graph prerequisites of this `Bijector`.
`is_constant_jacobian`	Python `bool` indicating that the Jacobian matrix is not a function of the input.
`validate_args`	Python `bool`, default `False`. Whether to validate input with asserts. If `validate_args` is `False`, and the inputs are invalid, correct behavior is not guaranteed.
`dtype`	`tf.dtype` supported by this `Bijector`. `None` means dtype is not enforced.
`forward_min_event_ndims`	Python `integer` indicating the minimum number of dimensions `forward` operates on.
`inverse_min_event_ndims`	Python `integer` indicating the minimum number of dimensions `inverse` operates on. Will be set to `forward_min_event_ndims` by default, if no value is provided.
`parameters`	Python `dict` of parameters used to instantiate this `Bijector`.
`name`	The name to give Ops created by the initializer.

Raises
`ValueError`	If neither `forward_min_event_ndims` and `inverse_min_event_ndims` are specified, or if either of them is negative.
`ValueError`	If a member of `graph_parents` is not a `Tensor`.

Attributes
`dtype`	dtype of `Tensor`s transformable by this distribution.
`forward_min_event_ndims`	Returns the minimal number of dimensions bijector.forward operates on.
`graph_parents`	Returns this `Bijector`'s graph_parents as a Python list.
`inverse_min_event_ndims`	Returns the minimal number of dimensions bijector.inverse operates on.
`is_constant_jacobian`	Returns true iff the Jacobian matrix is not a function of x. Note: Jacobian matrix is either constant for both forward and inverse or neither.
`name`	Returns the string name of this `Bijector`.
`parameters`	Dictionary of parameters used to instantiate this `Bijector`.
`trainable_variables`
`validate_args`	Returns True if Tensor arguments will be validated.
`variables`

Methods

`forward`

View source

forward(
    x, name='forward', **kwargs
)

Returns the forward Bijector evaluation, i.e., X = g(Y).

Args
`x`	`Tensor`. The input to the 'forward' evaluation.
`name`	The name to give this op.
`**kwargs`	Named arguments forwarded to subclass implementation.

Returns
`Tensor`.

Raises
`TypeError`	if `self.dtype` is specified and `x.dtype` is not `self.dtype`.
`NotImplementedError`	if `_forward` is not implemented.

`forward_dtype`

View source

forward_dtype(
    dtype, name='forward_dtype', **kwargs
)

Returns the dtype of the output of the forward transformation.

Args
`dtype`	`tf.dtype`, or nested structure of `tf.dtype`s, of the input to `forward`.
`name`	The name to give this op.
`**kwargs`	Named arguments forwarded to subclass implementation.

Returns
`tf.dtype` or nested structure of `tf.dtype`s of the output of `forward`.

`forward_event_shape`

View source

forward_event_shape(
    input_shape
)

Shape of a single sample from a single batch as a TensorShape.

Same meaning as forward_event_shape_tensor. May be only partially defined.

Args
`input_shape`	`TensorShape` indicating event-portion shape passed into `forward` function.

Returns
`forward_event_shape_tensor`	`TensorShape` indicating event-portion shape after applying `forward`. Possibly unknown.

`forward_event_shape_tensor`

View source

forward_event_shape_tensor(
    input_shape, name='forward_event_shape_tensor'
)

Shape of a single sample from a single batch as an int32 1D Tensor.

Args
`input_shape`	`Tensor`, `int32` vector indicating event-portion shape passed into `forward` function.
`name`	name to give to the op

Returns
`forward_event_shape_tensor`	`Tensor`, `int32` vector indicating event-portion shape after applying `forward`.

`forward_log_det_jacobian`

View source

forward_log_det_jacobian(
    x, event_ndims, name='forward_log_det_jacobian', **kwargs
)

Returns both the forward_log_det_jacobian.

Args
`x`	`Tensor`. The input to the 'forward' Jacobian determinant evaluation.
`event_ndims`	Number of dimensions in the probabilistic events being transformed. Must be greater than or equal to `self.forward_min_event_ndims`. The result is summed over the final dimensions to produce a scalar Jacobian determinant for each event, i.e. it has shape `rank(x) - event_ndims` dimensions.
`name`	The name to give this op.
`**kwargs`	Named arguments forwarded to subclass implementation.

Returns
`Tensor`, if this bijector is injective. If not injective this is not implemented.

Raises
`TypeError`	if `self.dtype` is specified and `y.dtype` is not `self.dtype`.
`NotImplementedError`	if neither `_forward_log_det_jacobian` nor {`_inverse`, `_inverse_log_det_jacobian`} are implemented, or this is a non-injective bijector.

`inverse`

View source

inverse(
    y, name='inverse', **kwargs
)

Returns the inverse Bijector evaluation, i.e., X = g^{-1}(Y).

Args
`y`	`Tensor`. The input to the 'inverse' evaluation.
`name`	The name to give this op.
`**kwargs`	Named arguments forwarded to subclass implementation.

Returns
`Tensor`, if this bijector is injective. If not injective, returns the k-tuple containing the unique `k` points `(x1, ..., xk)` such that `g(xi) = y`.

Raises
`TypeError`	if `self.dtype` is specified and `y.dtype` is not `self.dtype`.
`NotImplementedError`	if `_inverse` is not implemented.

`inverse_dtype`

View source

inverse_dtype(
    dtype, name='inverse_dtype', **kwargs
)

Returns the dtype of the output of the inverse transformation.

Args
`dtype`	`tf.dtype`, or nested structure of `tf.dtype`s, of the input to `inverse`.
`name`	The name to give this op.
`**kwargs`	Named arguments forwarded to subclass implementation.

Returns
`tf.dtype` or nested structure of `tf.dtype`s of the output of `inverse`.

`inverse_event_shape`

View source

inverse_event_shape(
    output_shape
)

Shape of a single sample from a single batch as a TensorShape.

Same meaning as inverse_event_shape_tensor. May be only partially defined.

Args
`output_shape`	`TensorShape` indicating event-portion shape passed into `inverse` function.

Returns
`inverse_event_shape_tensor`	`TensorShape` indicating event-portion shape after applying `inverse`. Possibly unknown.

`inverse_event_shape_tensor`

View source

inverse_event_shape_tensor(
    output_shape, name='inverse_event_shape_tensor'
)

Shape of a single sample from a single batch as an int32 1D Tensor.

Args
`output_shape`	`Tensor`, `int32` vector indicating event-portion shape passed into `inverse` function.
`name`	name to give to the op

Returns
`inverse_event_shape_tensor`	`Tensor`, `int32` vector indicating event-portion shape after applying `inverse`.

`inverse_log_det_jacobian`

View source

inverse_log_det_jacobian(
    y, event_ndims, name='inverse_log_det_jacobian', **kwargs
)

Returns the (log o det o Jacobian o inverse)(y).

Mathematically, returns: log(det(dX/dY))(Y). (Recall that: X=g^{-1}(Y).)

Note that forward_log_det_jacobian is the negative of this function, evaluated at g^{-1}(y).

Args
`y`	`Tensor`. The input to the 'inverse' Jacobian determinant evaluation.
`event_ndims`	Number of dimensions in the probabilistic events being transformed. Must be greater than or equal to `self.inverse_min_event_ndims`. The result is summed over the final dimensions to produce a scalar Jacobian determinant for each event, i.e. it has shape `rank(y) - event_ndims` dimensions.
`name`	The name to give this op.
`**kwargs`	Named arguments forwarded to subclass implementation.

Returns
`ildj`	`Tensor`, if this bijector is injective. If not injective, returns the tuple of local log det Jacobians, `log(det(Dg_i^{-1}(y)))`, where `g_i` is the restriction of `g` to the `ith` partition `Di`.

Raises
`TypeError`	if `self.dtype` is specified and `y.dtype` is not `self.dtype`.
`NotImplementedError`	if `_inverse_log_det_jacobian` is not implemented.

`call`

View source

__call__(
    value, name=None, **kwargs
)

Applies or composes the Bijector, depending on input type.

This is a convenience function which applies the Bijector instance in three different ways, depending on the input:

If the input is a tfd.Distribution instance, return tfd.TransformedDistribution(distribution=input, bijector=self).
If the input is a tfb.Bijector instance, return tfb.Chain([self, input]).
Otherwise, return self.forward(input)

Args
`value`	A `tfd.Distribution`, `tfb.Bijector`, or a `Tensor`.
`name`	Python `str` name given to ops created by this function.
`**kwargs`	Additional keyword arguments passed into the created `tfd.TransformedDistribution`, `tfb.Bijector`, or `self.forward`.

Returns
`composition`	A `tfd.TransformedDistribution` if the input was a `tfd.Distribution`, a `tfb.Chain` if the input was a `tfb.Bijector`, or a `Tensor` computed by `self.forward`.

Examples

sigmoid = tfb.Reciprocal()(
    tfb.AffineScalar(shift=1.)(
      tfb.Exp()(
        tfb.AffineScalar(scale=-1.))))
# ==> `tfb.Chain([
#         tfb.Reciprocal(),
#         tfb.AffineScalar(shift=1.),
#         tfb.Exp(),
#         tfb.AffineScalar(scale=-1.),
#      ])`  # ie, `tfb.Sigmoid()`

log_normal = tfb.Exp()(tfd.Normal(0, 1))
# ==> `tfd.TransformedDistribution(tfd.Normal(0, 1), tfb.Exp())`

tfb.Exp()([-1., 0., 1.])
# ==> tf.exp([-1., 0., 1.])

tfp.experimental.substrates.numpy.bijectors.CorrelationCholesky

Mathematical Details

Examples

References

Args

Raises

Attributes

Methods

forward

forward_dtype

forward_event_shape

forward_event_shape_tensor

forward_log_det_jacobian

inverse

inverse_dtype

inverse_event_shape

inverse_event_shape_tensor

inverse_log_det_jacobian

__call__

Examples

`forward`

`forward_dtype`

`forward_event_shape`

`forward_event_shape_tensor`

`forward_log_det_jacobian`

`inverse`

`inverse_dtype`

`inverse_event_shape`

`inverse_event_shape_tensor`

`inverse_log_det_jacobian`

`call`