Matrix-variate Distributions

size(d::MatrixDistribution)

Return the size of each sample from distribution d.

length(d::MatrixDistribution)

The length (i.e number of elements) of each sample from the distribution d.

rank(d::MatrixDistribution)

The rank of each sample from the distribution d.

mean(d::MatrixDistribution)

Return the mean matrix of d.

var(d::MatrixDistribution)

Compute the matrix of element-wise variances for distribution d.

cov(d::MatrixDistribution)

Compute the covariance matrix for vec(X), where X is a random matrix with distribution d.

pdf(d::MatrixDistribution, x::AbstractArray)

Compute the probability density at the input matrix x.

logpdf(d::MatrixDistribution, AbstractMatrix)

Compute the logarithm of the probability density at the input matrix x.

_rand!(::AbstractRNG, ::MatrixDistribution, A::AbstractMatrix)

Sample the matrix distribution and store the result in A. Must be implemented by matrix-variate distributions.

vec(d::MatrixDistribution)

If known, returns a MultivariateDistribution instance representing the distribution of vec(X), where X is a random matrix with distribution d.

MatrixNormal(M, U, V)

M::AbstractMatrix  n x p mean
U::AbstractPDMat   n x n row covariance
V::AbstractPDMat   p x p column covariance

The matrix normal distribution generalizes the multivariate normal distribution to $n\times p$ real matrices $\mathbf{X}$. If $\mathbf{X}\sim \textrm{MN}_{n,p}(\mathbf{M}, \mathbf{U}, \mathbf{V})$, then its probability density function is

\[f(\mathbf{X};\mathbf{M}, \mathbf{U}, \mathbf{V}) = \frac{\exp\left( -\frac{1}{2} \, \mathrm{tr}\left[ \mathbf{V}^{-1} (\mathbf{X} - \mathbf{M})^{\rm{T}} \mathbf{U}^{-1} (\mathbf{X} - \mathbf{M}) \right] \right)}{(2\pi)^{np/2} |\mathbf{V}|^{n/2} |\mathbf{U}|^{p/2}}.\]

$\mathbf{X}\sim \textrm{MN}_{n,p}(\mathbf{M},\mathbf{U},\mathbf{V})$ if and only if $\text{vec}(\mathbf{X})\sim \textrm{N}(\text{vec}(\mathbf{M}),\mathbf{V}\otimes\mathbf{U})$.

Wishart(ν, S)

ν::Real           degrees of freedom (whole number or a real number greater than p - 1)
S::AbstractPDMat  p x p scale matrix

The Wishart distribution generalizes the gamma distribution to $p\times p$ real, positive semidefinite matrices $\mathbf{H}$.

If $\nu>p-1$, then $\mathbf{H}\sim \textrm{W}_p(\nu, \mathbf{S})$ has rank $p$ and its probability density function is

\[f(\mathbf{H};\nu,\mathbf{S}) = \frac{1}{2^{\nu p/2} \left|\mathbf{S}\right|^{\nu/2} \Gamma_p\left(\frac {\nu}{2}\right ) }{\left|\mathbf{H}\right|}^{(\nu-p-1)/2} e^{-(1/2)\operatorname{tr}(\mathbf{S}^{-1}\mathbf{H})}.\]

If $\nu\leq p-1$, then $\mathbf{H}$ is rank $\nu$ and it has a density with respect to a suitably chosen volume element on the space of positive semidefinite matrices. See here.

For integer $\nu$, a random matrix given by

\[\mathbf{H} = \mathbf{X}\mathbf{X}^{\rm{T}}, \quad\mathbf{X} \sim \textrm{MN}_{p,\nu}(\mathbf{0}, \mathbf{S}, \mathbf{I}_{\nu})\]

has $\mathbf{H}\sim \textrm{W}_p(\nu, \mathbf{S})$. For non-integer $\nu$, Wishart matrices can be generated via the Bartlett decomposition.

InverseWishart(ν, Ψ)

ν::Real           degrees of freedom (greater than p - 1)
Ψ::AbstractPDMat  p x p scale matrix

The inverse Wishart distribution generalizes the inverse gamma distribution to $p\times p$ real, positive definite matrices $\boldsymbol{\Sigma}$. If $\boldsymbol{\Sigma}\sim \textrm{IW}_p(\nu,\boldsymbol{\Psi})$, then its probability density function is

\[f(\boldsymbol{\Sigma}; \nu,\boldsymbol{\Psi}) = \frac{\left|\boldsymbol{\Psi}\right|^{\nu/2}}{2^{\nu p/2}\Gamma_p(\frac{\nu}{2})} \left|\boldsymbol{\Sigma}\right|^{-(\nu+p+1)/2} e^{-\frac{1}{2}\operatorname{tr}(\boldsymbol{\Psi}\boldsymbol{\Sigma}^{-1})}.\]

$\mathbf{H}\sim \textrm{W}_p(\nu, \mathbf{S})$ if and only if $\mathbf{H}^{-1}\sim \textrm{IW}_p(\nu, \mathbf{S}^{-1})$.

MatrixReshaped(D, n, p)

D::MultivariateDistribution  base distribution
n::Integer   number of rows
p::Integer   number of columns

Reshapes a multivariate distribution into a matrix distribution with n rows and p columns.

MatrixTDist(ν, M, Σ, Ω)

ν::Real            positive degrees of freedom
M::AbstractMatrix  n x p location
Σ::AbstractPDMat   n x n scale
Ω::AbstractPDMat   p x p scale

The matrix t-distribution generalizes the multivariate t-distribution to $n\times p$ real matrices $\mathbf{X}$. If $\mathbf{X}\sim \textrm{MT}_{n,p}(\nu,\mathbf{M},\boldsymbol{\Sigma}, \boldsymbol{\Omega})$, then its probability density function is

\[f(\mathbf{X} ; \nu,\mathbf{M},\boldsymbol{\Sigma}, \boldsymbol{\Omega}) = c_0 \left|\mathbf{I}_n + \boldsymbol{\Sigma}^{-1}(\mathbf{X} - \mathbf{M})\boldsymbol{\Omega}^{-1}(\mathbf{X}-\mathbf{M})^{\rm{T}}\right|^{-\frac{\nu+n+p-1}{2}},\]

where

\[c_0=\frac{\Gamma_p\left(\frac{\nu+n+p-1}{2}\right)}{(\pi)^\frac{np}{2} \Gamma_p\left(\frac{\nu+p-1}{2}\right)} |\boldsymbol{\Omega}|^{-\frac{n}{2}} |\boldsymbol{\Sigma}|^{-\frac{p}{2}}.\]

If the joint distribution $p(\mathbf{S},\mathbf{X})=p(\mathbf{S})p(\mathbf{X}|\mathbf{S})$ is given by

\[\begin{aligned} \mathbf{S}&\sim \textrm{IW}_n(\nu + n - 1, \boldsymbol{\Sigma})\\ \mathbf{X}|\mathbf{S}&\sim \textrm{MN}_{n,p}(\mathbf{M}, \mathbf{S}, \boldsymbol{\Omega}), \end{aligned}\]

then the marginal distribution of $\mathbf{X}$ is $\textrm{MT}_{n,p}(\nu,\mathbf{M},\boldsymbol{\Sigma},\boldsymbol{\Omega})$.

MatrixBeta(p, n1, n2)

p::Int    dimension
n1::Real  degrees of freedom (greater than p - 1)
n2::Real  degrees of freedom (greater than p - 1)

The matrix beta distribution generalizes the beta distribution to $p\times p$ real matrices $\mathbf{U}$ for which $\mathbf{U}$ and $\mathbf{I}_p-\mathbf{U}$ are both positive definite. If $\mathbf{U}\sim \textrm{MB}_p(n_1/2, n_2/2)$, then its probability density function is

\[f(\mathbf{U}; n_1,n_2) = \frac{\Gamma_p(\frac{n_1+n_2}{2})}{\Gamma_p(\frac{n_1}{2})\Gamma_p(\frac{n_2}{2})} |\mathbf{U}|^{(n_1-p-1)/2}\left|\mathbf{I}_p-\mathbf{U}\right|^{(n_2-p-1)/2}.\]

If $\mathbf{S}_1\sim \textrm{W}_p(n_1,\mathbf{I}_p)$ and $\mathbf{S}_2\sim \textrm{W}_p(n_2,\mathbf{I}_p)$ are independent, and we use $\mathcal{L}(\cdot)$ to denote the lower Cholesky factor, then

\[\mathbf{U}=\mathcal{L}(\mathbf{S}_1+\mathbf{S}_2)^{-1}\mathbf{S}_1\mathcal{L}(\mathbf{S}_1+\mathbf{S}_2)^{-\rm{T}}\]

has $\mathbf{U}\sim \textrm{MB}_p(n_1/2, n_2/2)$.

MatrixFDist(n1, n2, B)

n1::Real          degrees of freedom (greater than p - 1)
n2::Real          degrees of freedom (greater than p - 1)
B::AbstractPDMat  p x p scale

The matrix F-distribution (sometimes called the matrix beta type II distribution) generalizes the F-Distribution to $p\times p$ real, positive definite matrices $\boldsymbol{\Sigma}$. If $\boldsymbol{\Sigma}\sim \textrm{MF}_{p}(n_1/2,n_2/2,\mathbf{B})$, then its probability density function is

\[f(\boldsymbol{\Sigma} ; n_1,n_2,\mathbf{B}) = \frac{\Gamma_p(\frac{n_1+n_2}{2})}{\Gamma_p(\frac{n_1}{2})\Gamma_p(\frac{n_2}{2})} |\mathbf{B}|^{n_2/2}|\boldsymbol{\Sigma}|^{(n_1-p-1)/2}|\mathbf{B}+\boldsymbol{\Sigma}|^{-(n_1+n_2)/2}.\]

If the joint distribution $p(\boldsymbol{\Psi},\boldsymbol{\Sigma})=p(\boldsymbol{\Psi})p(\boldsymbol{\Sigma}|\boldsymbol{\Psi})$ is given by

\[\begin{aligned} \boldsymbol{\Psi}&\sim \textrm{W}_p(n_1, \mathbf{B})\\ \boldsymbol{\Sigma}|\boldsymbol{\Psi}&\sim \textrm{IW}_p(n_2, \boldsymbol{\Psi}), \end{aligned}\]

then the marginal distribution of $\boldsymbol{\Sigma}$ is $\textrm{MF}_{p}(n_1/2,n_2/2,\mathbf{B})$.

LKJ(d, η)

d::Int   dimension
η::Real  positive shape

The LKJ distribution is a distribution over $d\times d$ real correlation matrices (positive-definite matrices with ones on the diagonal). If $\mathbf{R}\sim \textrm{LKJ}_{d}(\eta)$, then its probability density function is

\[f(\mathbf{R};\eta) = \left[\prod_{k=1}^{d-1}\pi^{\frac{k}{2}} \frac{\Gamma\left(\eta+\frac{d-1-k}{2}\right)}{\Gamma\left(\eta+\frac{d-1}{2}\right)}\right]^{-1} |\mathbf{R}|^{\eta-1}.\]

If $\eta = 1$, then the LKJ distribution is uniform over the space of correlation matrices.

_logpdf(d::MatrixDistribution, x::AbstractArray)

Evaluate logarithm of pdf value for a given sample x. This function need not perform dimension checking.