# Matrix-variate Distributions

Matrix-variate distributions are the distributions whose variate forms are Matrixvariate (i.e each sample is a matrix). Abstract types for matrix-variate distributions:

const MatrixDistribution{S<:ValueSupport} = Distribution{Matrixvariate,S}

const DiscreteMatrixDistribution   = Distribution{Matrixvariate, Discrete}
const ContinuousMatrixDistribution = Distribution{Matrixvariate, Continuous}

More advanced functionalities related to random matrices can be found in the RandomMatrices.jl package.

## Common Interface

All distributions implement the same set of methods:

Base.sizeMethod
size(d::MatrixDistribution)

Return the size of each sample from distribution d.

source
Base.lengthMethod
length(d::MatrixDistribution)

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

source
Statistics.varMethod
var(d::MatrixDistribution)

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

source
Statistics.covMethod
cov(d::MatrixDistribution)

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

source
Distributions.pdfMethod
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.

source
Distributions.logpdfMethod
logpdf(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 logpdf one should implement _logpdf(d, x) which does not have to check the size of x.

See also: pdf.

source
Missing docstring.

Missing docstring for Distributions._rand!(::AbstractRNG, ::MatrixDistribution, A::AbstractMatrix). Check Documenter's build log for details.

## Distributions

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

source
Distributions.WishartType
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.

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

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

source
Distributions.MatrixBetaType
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)$.

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

source
Distributions.LKJType
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.

Note

if a Cholesky factor of the correlation matrix is desired, it is more efficient to use LKJCholesky, which avoids factorizing the matrix.

source

## Internal Methods (for creating your own matrix-variate distributions)

Missing docstring.

Missing docstring for Distributions._logpdf(d::MatrixDistribution, x::AbstractMatrix{<:Real}). Check Documenter's build log for details.