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::Distribution{ArrayLikeVariate{N}}, x::AbstractArray{<:Real,N}) where {N}

Evaluate the probability density function of d at x.

This function checks if the size of x is compatible with distribution d. This check can be disabled by using @inbounds.

Implementation

Instead of pdf one should implement _pdf(d, x) which does not have to check the size of x. However, since the default definition of pdf(d, x) falls back to logpdf(d, x) usually it is sufficient to implement logpdf.

See also: logpdf.

logpdf(d::Distribution{ArrayLikeVariate{N}}, x::AbstractArray{<:Real,N}) where {N}

Evaluate the logarithm of the probability density function of d at x.

This function checks if the size of x is compatible with distribution d. This check can be disabled by using @inbounds.

Implementation

Instead of logpdf one should implement _logpdf(d, x) which does not have to check the size of x.

See also: pdf.

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})$.

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.