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'
)

This bijector is a mapping between R^{n} and the n-dimensional manifold of Cholesky-space correlation matrices embedded in R^{m^2}, where n is the (m - 1)th triangular number; i.e. n = 1 + 2 + ... + (m - 1).

Mathematical Details

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.

The CholeskyLKJ distribution [2] is a distribution on the set of Cholesky factors of positive definite correlation matrices. The CorrelationCholesky bijector provides a bijective mapping from unconstrained reals to the support of the CholeskyLKJ distribution.

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.
name: The name to give Ops created by the initializer.

Attributes:

dtype: dtype of Tensors 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.
trainable_variables
validate_args: Returns True if Tensor arguments will be validated.
variables

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.

Methods

`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.])

`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_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_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.