tf.contrib.distributions.WishartCholesky

The matrix Wishart distribution on positive definite matrices.

tf.contrib.distributions.WishartCholesky(
    df, scale, cholesky_input_output_matrices=False, validate_args=False,
    allow_nan_stats=True, name='WishartCholesky'
)

This distribution is defined by a scalar degrees of freedom df and a lower, triangular Cholesky factor which characterizes the scale matrix.

Using WishartCholesky is a constant-time improvement over WishartFull. It saves an O(nbk^3) operation, i.e., a matrix-product operation for sampling and a Cholesky factorization in log_prob. For most use-cases it often saves another O(nbk^3) operation since most uses of Wishart will also use the Cholesky factorization.

Mathematical Details

The probability density function (pdf) is,

pdf(X; df, scale) = det(X)**(0.5 (df-k-1)) exp(-0.5 tr[inv(scale) X]) / Z
Z = 2**(0.5 df k) |det(scale)|**(0.5 df) Gamma_k(0.5 df)

where:

df >= k denotes the degrees of freedom,
scale is a symmetric, positive definite, k x k matrix,
Z is the normalizing constant, and,
Gamma_k is the multivariate Gamma function.

Examples

import tensorflow_probability as tfp
tfd = tfp.distributions

# Initialize a single 3x3 Wishart with Cholesky factored scale matrix and 5
# degrees-of-freedom.(*)
df = 5
chol_scale = tf.linalg.cholesky(...)  # Shape is [3, 3].
dist = tfd.WishartCholesky(df=df, scale=chol_scale)

# Evaluate this on an observation in R^3, returning a scalar.
x = ...  # A 3x3 positive definite matrix.
dist.prob(x)  # Shape is [], a scalar.

# Evaluate this on a two observations, each in R^{3x3}, returning a length two
# Tensor.
x = [x0, x1]  # Shape is [2, 3, 3].
dist.prob(x)  # Shape is [2].

# Initialize two 3x3 Wisharts with Cholesky factored scale matrices.
df = [5, 4]
chol_scale = tf.linalg.cholesky(...)  # Shape is [2, 3, 3].
dist = tfd.WishartCholesky(df=df, scale=chol_scale)

# Evaluate this on four observations.
x = [[x0, x1], [x2, x3]]  # Shape is [2, 2, 3, 3].
dist.prob(x)  # Shape is [2, 2].

# (*) - To efficiently create a trainable covariance matrix, see the example
#   in tfp.distributions.matrix_diag_transform.

Args
`df`	`float` or `double` `Tensor`. Degrees of freedom, must be greater than or equal to dimension of the scale matrix.
`scale`	`float` or `double` `Tensor`. The Cholesky factorization of the symmetric positive definite scale matrix of the distribution.
`cholesky_input_output_matrices`	Python `bool`. Any function which whose input or output is a matrix assumes the input is Cholesky and returns a Cholesky factored matrix. Example `log_prob` input takes a Cholesky and `sample_n` returns a Cholesky when `cholesky_input_output_matrices=True`.
`validate_args`	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.
`allow_nan_stats`	Python `bool`, default `True`. When `True`, statistics (e.g., mean, mode, variance) use the value "`NaN`" to indicate the result is undefined. When `False`, an exception is raised if one or more of the statistic's batch members are undefined.
`name`	Python `str` name prefixed to Ops created by this class.

Attributes
`allow_nan_stats`	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.
`batch_shape`	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.
`cholesky_input_output_matrices`	Boolean indicating if `Tensor` input/outputs are Cholesky factorized.
`df`	Wishart distribution degree(s) of freedom.
`dimension`	Dimension of underlying vector space. The `p` in `R^(p*p)`.
`dtype`	The `DType` of `Tensor`s handled by this `Distribution`.
`event_shape`	Shape of a single sample from a single batch as a `TensorShape`. May be partially defined or unknown.
`name`	Name prepended to all ops created by this `Distribution`.
`parameters`	Dictionary of parameters used to instantiate this `Distribution`.
`reparameterization_type`	Describes how samples from the distribution are reparameterized. Currently this is one of the static instances `distributions.FULLY_REPARAMETERIZED` or `distributions.NOT_REPARAMETERIZED`.
`scale_operator`	Wishart distribution scale matrix as an Linear Operator.
`validate_args`	Python `bool` indicating possibly expensive checks are enabled.

Args
`value`	`float` or `double` `Tensor`.
`name`	Python `str` prepended to names of ops created by this function.

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

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

Args
`sample_shape`	0D or 1D `int32` `Tensor`. Shape of the generated samples.
`seed`	Python integer seed for RNG
`name`	name to give to the op.

tf.contrib.distributions.WishartCholesky

Mathematical Details

Examples

Methods

batch_shape_tensor

cdf

copy

covariance

cross_entropy

entropy

event_shape_tensor

is_scalar_batch

is_scalar_event

kl_divergence

log_cdf

log_normalization

log_prob

log_survival_function

mean

mean_log_det

mode

param_shapes

param_static_shapes

prob

quantile

sample

scale

stddev

survival_function

variance

`batch_shape_tensor`

`cdf`

`copy`

`covariance`

`cross_entropy`

`entropy`

`event_shape_tensor`

`is_scalar_batch`

`is_scalar_event`

`kl_divergence`

`log_cdf`

`log_normalization`

`log_prob`

`log_survival_function`

`mean`

`mean_log_det`

`mode`

`param_shapes`

`param_static_shapes`

`prob`

`quantile`

`sample`

`scale`

`stddev`

`survival_function`

`variance`