Multivariate Distributions¶
Multivariate distributions are the distributions whose variate forms are Multivariate
(i.e each sample is a vector). Abstract types for multivariate distributions:
const MultivariateDistribution{S<:ValueSupport} = Distribution{Multivariate,S}
const DiscreteMultivariateDistribution = Distribution{Multivariate, Discrete}
const ContinuousMultivariateDistribution = Distribution{Multivariate, Continuous}
Common Interface¶
The methods listed as below are implemented for each multivariate distribution, which provides a consistent interface to work with multivariate distributions.
Computation of statistics¶

length
(d)¶ Return the sample dimension of distribution
d
.

size
(d)¶ Return the sample size of distribution
d
, i.e(length(d), 1)
.

mean
(d)¶ Return the mean vector of distribution
d
.

var
(d)¶ Return the vector of componentwise variances of distribution
d
.

cov
(d)¶ Return the covariance matrix of distribution
d
.

cor
(d)¶ Return the correlation matrix of distribution
d
.

entropy
(d)¶ Return the entropy of distribution
d
.
Probability evaluation¶

insupport
(d, x)¶ If
x
is a vector, it returns whether x is within the support ofd
. Ifx
is a matrix, it returns whether every column inx
is within the support ofd
.

pdf
(d, x)¶ Return the probability density of distribution
d
evaluated atx
. If
x
is a vector, it returns the result as a scalar.  If
x
is a matrix with n columns, it returns a vectorr
of length n, wherer[i]
corresponds tox[:,i]
(i.e. treating each column as a sample).
 If

pdf!(r, d, x)
Evaluate the probability densities at columns of x, and write the results to a preallocated array r.

logpdf
(d, x)¶ Return the logarithm of probability density evaluated at
x
. If
x
is a vector, it returns the result as a scalar.  If
x
is a matrix with n columns, it returns a vectorr
of length n, wherer[i]
corresponds tox[:,i]
.
 If

logpdf!(r, d, x)
Evaluate the logarithm of probability densities at columns of x, and write the results to a preallocated array r.

loglikelihood
(d, x)¶ The loglikelihood of distribution
d
w.r.t. all columns contained in matrixx
.
Note: For multivariate distributions, the pdf value is usually very small or large, and therefore direct evaluating the pdf may cause numerical problems. It is generally advisable to perform probability computation in logscale.
Sampling¶

rand
(d)¶ Sample a vector from the distribution
d
.

rand
(d, n) Sample n vectors from the distribution
d
. This returns a matrix of size(dim(d), n)
, where each column is a sample.

rand!(d, x)
Draw samples and output them to a preallocated array x. Here, x can be either a vector of length
dim(d)
or a matrix withdim(d)
rows.
Node: In addition to these common methods, each multivariate distribution has its own special methods, as introduced below.
Multinomial Distribution¶
The Multinomial distribution generalizes the binomial distribution. Consider n independent draws from a Categorical distribution over a finite set of size k, and let \(X = (X_1, ..., X_k)\) where X_i
represents the number of times the element i
occurs, then the distribution of X
is a multinomial distribution. Each sample of a multinomial distribution is a kdimensional integer vector that sums to n.
The probability mass function is given by
Multinomial(n, p) # Multinomial distribution for n trials with probability vector p
Multinomial(n, k) # Multinomial distribution for n trials with equal probabilities
# over 1:k
Multivariate Normal Distribution¶
The Multivariate normal distribution is a multidimensional generalization of the normal distribution. The probability density function of a ddimensional multivariate normal distribution with mean vector \(\boldsymbol{\mu}\) and covariance matrix \(\boldsymbol{\Sigma}\) is
We realize that the mean vector and the covariance often have special forms in practice, which can be exploited to simplify the computation. For example, the mean vector is sometimes just a zero vector, while the covariance matrix can be a diagonal matrix or even in the form of \(\sigma \mathbf{I}\). To take advantage of such special cases, we introduce a parametric type MvNormal
, defined as below, which allows users to specify the special structure of the mean and covariance.
immutable MvNormal{Cov<:AbstractPDMat,Mean<:Union{Vector,ZeroVector}} <: AbstractMvNormal
μ::Mean
Σ::Cov
end
Here, the mean vector can be an instance of either Vector
or ZeroVector
, where the latter is simply an empty type indicating a vector filled with zeros. The covariance can be of any subtype of AbstractPDMat
. Particularly, one can use PDMat
for full covariance, PDiagMat
for diagonal covariance, and ScalMat
for the isotropic covariance – those in the form of \(\sigma \mathbf{I}\). (See the Julia package PDMats for details).
We also define a set of alias for the types using different combinations of mean vectors and covariance:
const IsoNormal = MvNormal{ScalMat, Vector{Float64}}
const DiagNormal = MvNormal{PDiagMat, Vector{Float64}}
const FullNormal = MvNormal{PDMat, Vector{Float64}}
const ZeroMeanIsoNormal = MvNormal{ScalMat, ZeroVector{Float64}}
const ZeroMeanDiagNormal = MvNormal{PDiagMat, ZeroVector{Float64}}
const ZeroMeanFullNormal = MvNormal{PDMat, ZeroVector{Float64}}
Construction¶
Generally, users don’t have to worry about these internal details. We provide a common constructor MvNormal
, which will construct a distribution of appropriate type depending on the input arguments.

MvNormal
(mu, sig)¶ Construct a multivariate normal distribution with mean
mu
and covariance represented bysig
.Parameters:  mu – The mean vector, of type
Vector{T}
, withT<:Real
.  sig –
The covariance, which can in of either of the following forms (with
T<:Real
): an instance of a subtype of
AbstractPDMat
 a symmetric matrix of type
Matrix{T}
 a vector of type
Vector{T}
: indicating a diagonal covariance asdiagm(abs2(sig))
.  a realvalued number: indicating an isotropic covariance as
abs2(sig) * eye(d)
.
 an instance of a subtype of
 mu – The mean vector, of type

MvNormal
(sig) Construct a multivariate normal distribution with zero mean and covariance represented by
sig
.Here,
sig
can be in either of the following forms (withT<:Real
): an instance of a subtype of
AbstractPDMat
 a symmetric matrix of type
Matrix{T}
 a vector of type
Vector{T}
: indicating a diagonal covariance asdiagm(abs2(sig))
.
 an instance of a subtype of

MvNormal
(d, sig) Construct a multivariate normal distribution of dimension
d
, with zero mean, and an isotropic covariance asabs2(sig) * eye(d)
.
Note: The constructor will choose an appropriate covariance form internally, so that special structure of the covariance can be exploited.
Addition Methods¶
In addition to the methods listed in the common interface above, we also provide the followinig methods for all multivariate distributions under the base type AbstractMvNormal
:

invcov
(d)¶ Return the inversed covariance matrix of d.

logdetcov
(d)¶ Return the logdeterminant value of the covariance matrix.

sqmahal
(d, x)¶ Return the squared Mahalanobis distance from x to the center of d, w.r.t. the covariance.
When x is a vector, it returns a scalar value. When x is a matrix, it returns a vector of length size(x,2).

sqmahal!(r, d, x)
Write the squared Mahalanbobis distances from each column of x to the center of d to r.

rand
(rng, d) 
rand
(rng, d, n) 
rand!(rng, d, x)
Sample from distribution
d
using the random number generatorrng
.
Canonical form¶
Multivariate normal distribution is an exponential family distribution, with two canonical parameters: the potential vector \(\mathbf{h}\) and the precision matrix \(\mathbf{J}\). The relation between these parameters and the conventional representation (i.e. the one using mean \(\boldsymbol{mu}\) and covariance \(\boldsymbol{\Sigma}\)) is:
The canonical parameterization is widely used in Bayesian analysis. We provide a type MvNormalCanon
, which is also a subtype of AbstractMvNormal
to represent a multivariate normal distribution using canonical parameters. Particularly, MvNormalCanon
is defined as:
immutable MvNormalCanon{P<:AbstractPDMat,V<:Union{Vector,ZeroVector}} <: AbstractMvNormal
μ::V # the mean vector
h::V # potential vector, i.e. inv(Σ) * μ
J::P # precision matrix, i.e. inv(Σ)
end
We also define aliases for common specializations of this parametric type:
const FullNormalCanon = MvNormalCanon{PDMat, Vector{Float64}}
const DiagNormalCanon = MvNormalCanon{PDiagMat, Vector{Float64}}
const IsoNormalCanon = MvNormalCanon{ScalMat, Vector{Float64}}
const ZeroMeanFullNormalCanon = MvNormalCanon{PDMat, ZeroVector{Float64}}
const ZeroMeanDiagNormalCanon = MvNormalCanon{PDiagMat, ZeroVector{Float64}}
const ZeroMeanIsoNormalCanon = MvNormalCanon{ScalMat, ZeroVector{Float64}}
A multivariate distribution with canonical parameterization can be constructed using a common constructor MvNormalCanon
as:

MvNormalCanon
(h, J)¶ Construct a multivariate normal distribution with potential vector
h
and precision matrix represented byJ
.Parameters:  h – the potential vector, of type
Vector{T}
withT<:Real
.  J –
the representation of the precision matrix, which can be in either of the following forms (
T<:Real
): an instance of a subtype of
AbstractPDMat
 a square matrix of type
Matrix{T}
 a vector of type
Vector{T}
: indicating a diagonal precision matrix asdiagm(J)
.  a real number: indicating an isotropic precision matrix as
J * eye(d)
.
 an instance of a subtype of
 h – the potential vector, of type

MvNormalCanon
(J) Construct a multivariate normal distribution with zero mean (thus zero potential vector) and precision matrix represented by
J
.Here,
J
represents the precision matrix, which can be in either of the following forms (T<:Real
): an instance of a subtype of
AbstractPDMat
 a square matrix of type
Matrix{T}
 a vector of type
Vector{T}
: indicating a diagonal precision matrix asdiagm(J)
.
 an instance of a subtype of

MvNormalCanon
(d, v) Construct a multivariate normal distribution of dimension
d
, with zero mean and a precision matrix asv * eye(d)
.
Note: MvNormalCanon
share the same set of methods as MvNormal
.
Multivariate Lognormal Distribution¶
The Multivariate lognormal distribution is a multidimensional generalization of the lognormal distribution.
If \(\boldsymbol X \sim \mathcal{N}(\boldsymbol\mu,\,\boldsymbol\Sigma)\) has a multivariate normal distribution then \(\boldsymbol Y=\exp(\boldsymbol X)\) has a multivariate lognormal distribution.
Mean vector \(\boldsymbol{\mu}\) and covariance matrix \(\boldsymbol{\Sigma}\) of the underlying normal distribution are known as the location and scale parameters of the corresponding lognormal distribution.
The package provides an implementation, MvLogNormal
, which wraps around MvNormal
:
immutable MvLogNormal <: AbstractMvLogNormal
normal::MvNormal
end
Construction¶
MvLogNormal
provides the same constructors as MvNormal
. See above for details.
Additional Methods¶
In addition to the methods listed in the common interface above, we also provide the following methods:

location
(d)¶ Return the location vector of the distribution (the mean of the underlying normal distribution).

scale
(d)¶ Return the scale matrix of the distribution (the covariance matrix of the underlying normal distribution).

median
(d)¶ Return the median vector of the lognormal distribution. which is strictly smaller than the mean.

mode
(d)¶ Return the mode vector of the lognormal distribution, which is strictly smaller than the mean and median.
Conversion Methods¶
It can be necessary to calculate the parameters of the lognormal (location vector and scale matrix) from a given covariance and mean, median or mode. To that end, the following functions are provided.

location{D<:AbstractMvLogNormal}(::Type{D},s::Symbol,m::AbstractVector,S::AbstractMatrix)
Calculate the location vector (the mean of the underlying normal distribution).
If
s == :meancov
, then m is taken as the mean, and S the covariance matrix of a lognormal distribution.If
s == :mean  :median  :mode
, then m is taken as the mean, median or mode of the lognormal respectively, and S is interpreted as the scale matrix (the covariance of the underlying normal distribution).It is not possible to analytically calculate the location vector from e.g., median + covariance, or from mode + covariance.

location!{D<:AbstractMvLogNormal}(::Type{D},s::Symbol,m::AbstractVector,S::AbstractMatrix,μ::AbstractVector)
Calculate the location vector (as above) and store the result in
μ

scale{D<:AbstractMvLogNormal}(::Type{D},s::Symbol,m::AbstractVector,S::AbstractMatrix)
Calculate the scale parameter, as defined for the location parameter above.

scale!{D<:AbstractMvLogNormal}(::Type{D},s::Symbol,m::AbstractVector,S::AbstractMatrix,Σ::AbstractMatrix)
Calculate the scale parameter, as defined for the location parameter above and store the result in
Σ
.

params{D<:AbstractMvLogNormal}(::Type{D},m::AbstractVector,S::AbstractMatrix)
Return (scale,location) for a given mean and covariance

params!{D<:AbstractMvLogNormal}(::Type{D},m::AbstractVector,S::AbstractMatrix,μ::AbstractVector,Σ::AbstractMatrix)
Calculate (scale,location) for a given mean and covariance, and store the results in
μ
andΣ
Dirichlet Distribution¶
The Dirichlet distribution is often used the conjugate prior for Categorical or Multinomial distributions. The probability density function of a Dirichlet distribution with parameter \(\alpha = (\alpha_1, \ldots, \alpha_k)\) is
# Let alpha be a vector
Dirichlet(alpha) # Dirichlet distribution with parameter vector alpha
# Let a be a positive scalar
Dirichlet(k, a) # Dirichlet distribution with parameter a * ones(k)