# Covariance Matrix Distributions

The covariance matrix distributions have support on symmetric, positive-definite $$K \times K$$ matrices or their Cholesky factors (square, lower triangular matrices with positive diagonal elements).

## Wishart distribution

### Probability density function

If $$K \in \mathbb{N}$$, $$\nu \in (K-1,\infty)$$, and $$S \in \mathbb{R}^{K \times K}$$ is symmetric and positive definite, then for symmetric and positive-definite $$W \in \mathbb{R}^{K \times K}$$, $\begin{equation*} \text{Wishart}(W \mid \nu,S) = \frac{1}{2^{\nu K / 2}} \ \frac{1}{\Gamma_K \! \left( \frac{\nu}{2} \right)} \ \left| S \right|^{-\nu/2} \ \left| W \right|^{(\nu - K - 1)/2} \ \exp \! \left(- \frac{1}{2} \ \text{tr}\left( S^{-1} W \right) \right) \! , \end{equation*}$ where $$\text{tr}()$$ is the matrix trace function, and $$\Gamma_K()$$ is the multivariate Gamma function, $\begin{equation*} \Gamma_K(x) = \frac{1}{\pi^{K(K-1)/4}} \ \prod_{k=1}^K \Gamma \left( x + \frac{1 - k}{2} \right) \!. \end{equation*}$

### Distribution statement

W ~ wishart(nu, Sigma)

Increment target log probability density with wishart_lupdf(W | nu, Sigma).

Available since 2.0

### Stan functions

real wishart_lpdf(matrix W | real nu, matrix Sigma)
Return the log of the Wishart density for symmetric and positive-definite matrix W given degrees of freedom nu and symmetric and positive-definite scale matrix Sigma.

Available since 2.12

real wishart_lupdf(matrix W | real nu, matrix Sigma)
Return the log of the Wishart density for symmetric and positive-definite matrix W given degrees of freedom nu and symmetric and positive-definite scale matrix Sigma dropping constant additive terms.

Available since 2.25

matrix wishart_rng(real nu, matrix Sigma)
Generate a Wishart variate with degrees of freedom nu and symmetric and positive-definite scale matrix Sigma; may only be used in transformed data and generated quantities blocks.

Available since 2.0

## Wishart distribution, Cholesky Parameterization

The Cholesky parameterization of the Wishart distribution uses a Cholesky factor for both the variate and the parameter. If $$S$$ and $$W$$ are positive definite matrices with Cholesky factors $$L_S$$ and $$L_W$$ (i.e., $$S = L_S L_S^{\top}$$ and $$W = L_W L_W^{\top}$$), then the Cholesky parameterization is defined so that $\begin{equation*} L_W \sim \textrm{WishartCholesky}(\nu, L_S) \end{equation*}$ if and only if $\begin{equation*} W \sim \textrm{Wishart}(\nu, S). \end{equation*}$

### Probability density function

If $$K \in \mathbb{N}$$, $$\nu \in (K-1, \infty)$$, and $$L_S, L_W \in \mathbb{R}^{K \times K}$$ are lower triangular matrixes with positive diagonal elements, then the Cholesky parameterized Wishart density is $\begin{equation*} \text{WishartCholesky}(L_W \mid \nu,L_S) = \text{Wishart}(L_W L_W^{\top} \mid \nu,L_S L_S^{\top}) \, \left| J_{f^{-1}} \right|, \end{equation*}$ where $$J_{f^{-1}}$$ is the Jacobian of the (inverse) transform of the variate, $$f^{-1}(L_W) = L_W L_W^{\top}$$. The log absolute determinant is $\begin{equation*} \log \left| J_{f^{-1}} \right| = K \log(2) + \sum_{k=1}^K (K - k + 1) \log {(L_W)_{k,\, k}}. \end{equation*}$

The probability functions will raise errors if $$\nu \leq K - 1$$ or if $$L_S$$ and $$L_W$$ are not Cholesky factors (square, lower-triangular matrices with positive diagonal elements) of the same size.

### Stan functions

real wishart_cholesky_lpdf(matrix L_W | real nu, matrix L_S)
Return the log of the Wishart density for lower-triangular Cholesky factor L_W given degrees of freedom nu and lower-triangular Cholesky factor of the scale matrix L_S.

Available since 2.30

real wishart_cholesky_lupdf(matrix L_W | real nu, matrix L_S)
Return the log of the Wishart density for lower-triangular Cholesky factor of L_W given degrees of freedom nu and lower-triangular Cholesky factor of the scale matrix L_S dropping constant additive terms.

Available since 2.30

matrix wishart_cholesky_rng(real nu, matrix L_S)
Generate the Cholesky factor of a Wishart variate with degrees of freedom nu and lower-triangular Cholesky factor of the scale matrix L_S; may only be used in transformed data and generated quantities blocks

Available since 2.30

## Inverse Wishart distribution

### Probability density function

If $$K \in \mathbb{N}$$, $$\nu \in (K-1,\infty)$$, and $$S \in \mathbb{R}^{K \times K}$$ is symmetric and positive definite, then for symmetric and positive-definite $$W \in \mathbb{R}^{K \times K}$$, $\begin{equation*} \text{InvWishart}(W \mid \nu,S) = \frac{1}{2^{\nu K / 2}} \ \frac{1}{\Gamma_K \! \left( \frac{\nu}{2} \right)} \ \left| S \right|^{\nu/2} \ \left| W \right|^{-(\nu + K + 1)/2} \ \exp \! \left( - \frac{1}{2} \ \text{tr}(SW^{-1}) \right) \! . \end{equation*}$

### Distribution statement

W ~ inv_wishart(nu, Sigma)

Increment target log probability density with inv_wishart_lupdf(W | nu, Sigma).

Available since 2.0

### Stan functions

real inv_wishart_lpdf(matrix W | real nu, matrix Sigma)
Return the log of the inverse Wishart density for symmetric and positive-definite matrix W given degrees of freedom nu and symmetric and positive-definite scale matrix Sigma.

Available since 2.12

real inv_wishart_lupdf(matrix W | real nu, matrix Sigma)
Return the log of the inverse Wishart density for symmetric and positive-definite matrix W given degrees of freedom nu and symmetric and positive-definite scale matrix Sigma dropping constant additive terms.

Available since 2.25

matrix inv_wishart_rng(real nu, matrix Sigma)
Generate an inverse Wishart variate with degrees of freedom nu and symmetric and positive-definite scale matrix Sigma; may only be used in transformed data and generated quantities blocks.

Available since 2.0

## Inverse Wishart distribution, Cholesky Parameterization

The Cholesky parameterization of the inverse Wishart distribution uses a Cholesky factor for both the variate and the parameter. If $$S$$ and $$W$$ are positive definite matrices with Cholesky factors $$L_S$$ and $$L_W$$ (i.e., $$S = L_S L_S^{\top}$$ and $$W = L_W L_W^{\top}$$), then the Cholesky parameterization is defined so that $\begin{equation*} L_W \sim \textrm{InvWishartCholesky}(\nu, L_S) \end{equation*}$ if and only if $\begin{equation*} W \sim \textrm{InvWishart}(\nu, S). \end{equation*}$

### Probability density function

If $$K \in \mathbb{N}$$, $$\nu \in (K-1, \infty)$$, and $$L_S, L_W \in \mathbb{R}^{K \times K}$$ are lower triangular matrixes with positive diagonal elements, then the Cholesky parameterized inverse Wishart density is $\begin{equation*} \text{InvWishartCholesky}(L_W \mid \nu,L_S) = \text{InvWishart}(L_WL_W^{\top} \mid \nu, L_S L_S^{\top}) \, \left| J_{f^{-1}} \right|, \end{equation*}$ where $$J_{f^{-1}}$$ is the Jacobian of the (inverse) transform of the variate, $$f^{-1}(L_W) = L_W L_W^{\top}$$. The log absolute determinant is $\begin{equation*} \log \left| J_{f^{-1}} \right| = K \log(2) + \sum_{k=1}^K (K - k + 1) \log {(L_W)_{k,\, k}}. \end{equation*}$

The probability functions will raise errors if $$\nu \leq K - 1$$ or if $$L_S$$ and $$L_W$$ are not Cholesky factors (square, lower-triangular matrices with positive diagonal elements) of the same size.

### Stan functions

real inv_wishart_cholesky_lpdf(matrix L_W | real nu, matrix L_S)
Return the log of the inverse Wishart density for lower-triangular Cholesky factor L_W given degrees of freedom nu and lower-triangular Cholesky factor of the scale matrix L_S.

Available since 2.30

real inv_wishart_cholesky_lupdf(matrix L_W | real nu, matrix L_S)
Return the log of the inverse Wishart density for lower-triangular Cholesky factor of L_W given degrees of freedom nu and lower-triangular Cholesky factor of the scale matrix L_S dropping constant additive terms.

Available since 2.30

matrix inv_wishart_cholesky_rng(real nu, matrix L_S)
Generate the Cholesky factor of an inverse Wishart variate with degrees of freedom nu and lower-triangular Cholesky factor of the scale matrix L_S; may only be used in transformed data and generated quantities blocks.

Available since 2.30