# Wishart

Source: https://www.tensorplay.cn/docs/generated/tensorplay.distributions.Wishart.html

```python
class tensorplay.distributions.Wishart(df: Tensor | bool | int | float, covariance_matrix: Tensor | None = None, precision_matrix: Tensor | None = None, scale_tril: Tensor | None = None, validate_args: bool | None = None)
```

Creates a Wishart distribution parameterized by a symmetric positive definite matrix $\Sigma$,
or its Cholesky decomposition $\mathbf{\Sigma} = \mathbf{L}\mathbf{L}^\top$

Example

```
>>> # xdoctest: +SKIP("FIXME: scale_tril must be at least two-dimensional")
>>> m = Wishart(tensorplay.Tensor([2]), covariance_matrix=tensorplay.eye(2))
>>> m.sample()  # Wishart distributed with mean=`df * I` and
>>> # variance(x_ij)=`df` for i != j and variance(x_ij)=`2 * df` for i == j
```

Parameters:

- df ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – real-valued parameter larger than the (dimension of Square matrix) - 1

- covariance_matrix ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – positive-definite covariance matrix

- precision_matrix ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – positive-definite precision matrix

- scale_tril ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – lower-triangular factor of covariance, with positive-valued diagonal

> **Note**
>
> Only one of covariance_matrix or precision_matrix or scale_tril can be specified. Using scale_tril will be more efficient: all computations internally are based on scale_tril. If covariance_matrix or precision_matrix is passed instead, it is only used to compute the corresponding lower triangular matrices using a Cholesky decomposition. ‘tensorplay.distributions.LKJCholesky’ is a restricted Wishart distribution.[1]

References

[1] Wang, Z., Wu, Y. and Chu, H., 2018. On equivalence of the LKJ distribution and the restricted Wishart distribution.
[2] Sawyer, S., 2007. Wishart Distributions and Inverse-Wishart Sampling.
[3] Anderson, T. W., 2003. An Introduction to Multivariate Statistical Analysis (3rd ed.).
[4] Odell, P. L. & Feiveson, A. H., 1966. A Numerical Procedure to Generate a Sample Covariance Matrix. JASA, 61(313):199-203.
[5] Ku, Y.-C. & Bloomfield, P., 2010. Generating Random Wishart Matrices with Fractional Degrees of Freedom in OX.

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
cdf(value: Tensor) → Tensor
```

Returns the cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
enumerate_support(expand: bool = True) → Tensor
```

Returns tensor containing all values supported by a discrete
distribution. The result will enumerate over dimension 0, so the shape
of the result will be (cardinality,) + batch_shape + event_shape
(where event_shape = () for univariate distributions).

Note that this enumerates over all batched tensors in lock-step
[[0, 0], [1, 1], …]. With expand=False, enumeration happens
along dim 0, but with the remaining batch dimensions being
singleton dimensions, [[0], [1], ...

To iterate over the full Cartesian product use
itertools.product(m.enumerate_support()).

Parameters:

expand ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – whether to expand the support over the
batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
icdf(value: Tensor) → Tensor
```

Returns the inverse cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
rsample(sample_shape: Size | Sequence[int] = (), max_try_correction=None) → Tensor
```

> **Warning**
>
> In some cases, sampling algorithm based on Bartlett decomposition may return singular matrix samples. Several tries to correct singular samples are performed by default, but it may end up returning singular matrix samples. Singular samples may return -inf values in .log_prob(). In those cases, the user should validate the samples and either fix the value of df or adjust max_try_correction value for argument in .rsample accordingly.

```python
sample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

Generates a sample_shape shaped sample or sample_shape shaped batch of
samples if the distribution parameters are batched.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

```python
property stddev: Tensor
```

Returns the standard deviation of the distribution.