Engee documentation

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:

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.

Distributions

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 real matrices . If , then its probability density function is

if and only if .

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 real, positive semidefinite matrices .

If , then has rank and its probability density function is

If , then is rank and it has a density with respect to a suitably chosen volume element on the space of positive semidefinite matrices. See here.

For integer , a random matrix given by

has . For non-integer , 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 real, positive definite matrices . If , then its probability density function is

if and only if .

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 real matrices . If , then its probability density function is

where

If the joint distribution is given by

then the marginal distribution of is .

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 real matrices for which and are both positive definite. If , then its probability density function is

If and are independent, and we use to denote the lower Cholesky factor, then

has .

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 real, positive definite matrices . If , then its probability density function is

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

\boldsymbol{\Psi})$ is given by

then the marginal distribution of is .

LKJ(d, η)
d::Int   dimension
η::Real  positive shape

The LKJ distribution is a distribution over real correlation matrices (positive-definite matrices with ones on the diagonal). If , then its probability density function is

If , then the LKJ distribution is uniform over the space of correlation matrices.

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

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

Index