# 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

`Base.length`

— Method.`length(d::MultivariateDistribution) -> Int`

Return the sample dimension of distribution `d`

.

`Base.size`

— Method.`size(d::MultivariateDistribution)`

Return the sample size of distribution `d`

, *i.e* `(length(d),)`

.

`Base.eltype`

— Method.`eltype(::Type{Sampleable})`

The default element type of a sample. This is the type of elements of the samples generated by the `rand`

method. However, one can provide an array of different element types to store the samples using `rand!`

.

`Statistics.mean`

— Method.`mean(d::MultivariateDistribution)`

Compute the mean vector of distribution `d`

.

`Statistics.var`

— Method.`var(d::MultivariateDistribution)`

Compute the vector of element-wise variances for distribution `d`

.

`Statistics.cov`

— Method.`cov(d::MultivariateDistribution)`

Compute the covariance matrix for distribution `d`

. (`cor`

is provided based on `cov`

).

`Statistics.cor`

— Method.`cor(d::MultivariateDistribution)`

Computes the correlation matrix for distribution `d`

.

`StatsBase.entropy`

— Method.`entropy(d::MultivariateDistribution)`

Compute the entropy value of distribution `d`

.

`StatsBase.entropy`

— Method.`entropy(d::MultivariateDistribution, b::Real)`

Compute the entropy value of distribution $d$, w.r.t. a given base.

### Probability evaluation

`Distributions.insupport`

— Method.`insupport(d::MultivariateDistribution, x::AbstractArray)`

If $x$ is a vector, it returns whether x is within the support of $d$. If $x$ is a matrix, it returns whether every column in $x$ is within the support of $d$.

`Distributions.pdf`

— Method.`pdf(d::MultivariateDistribution, x::AbstractArray)`

Return the probability density of distribution `d`

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 vector`r`

of length n, where`r[i]`

corresponds

to `x[:,i]`

(i.e. treating each column as a sample).

`pdf!(r, d, x)`

will write the results to a pre-allocated array `r`

.

`Distributions.logpdf`

— Method.`logpdf(d::MultivariateDistribution, x::AbstractArray)`

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 vector`r`

of length n, where`r[i]`

corresponds to`x[:,i]`

.

`logpdf!(r, d, x)`

will write the results to a pre-allocated array `r`

.

Missing docstring for `loglikelihood(::MultivariateDistribution, ::AbstractArray)`

. Check Documenter's build log for details.

**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 log-scale.

### Sampling

`Base.rand`

— Method.`rand(::AbstractRNG, ::Sampleable)`

Samples from the sampler and returns the result.

`Random.rand!`

— Method.`rand!([rng::AbstractRNG,] d::MultivariateDistribution, x::AbstractArray)`

Draw samples and output them to a pre-allocated array x. Here, x can be either a vector of length `dim(d)`

or a matrix with `dim(d)`

rows.

**Note:** In addition to these common methods, each multivariate distribution has its own special methods, as introduced below.

## Distributions

`Distributions.Multinomial`

— Type.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 k-dimensional 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
```

`Distributions.AbstractMvNormal`

— Type.The Multivariate normal distribution is a multidimensional generalization of the *normal distribution*. The probability density function of a d-dimensional 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^2 \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.

```
struct MvNormal{Cov<:AbstractPDMat,Mean<:AbstractVector} <: AbstractMvNormal
μ::Mean
Σ::Cov
end
```

Here, the mean vector can be an instance of any `AbstractVector`

. 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{Axes} = MvNormal{ScalMat, Zeros{Float64,1,Axes}}
const ZeroMeanDiagNormal{Axes} = MvNormal{PDiagMat, Zeros{Float64,1,Axes}}
const ZeroMeanFullNormal{Axes} = MvNormal{PDMat, Zeros{Float64,1,Axes}}
```

Multivariate normal distributions support affine transformations:

```
d = MvNormal(μ, Σ)
c + B * d # == MvNormal(B * μ + c, B * Σ * B')
dot(b, d) # == Normal(dot(b, μ), b' * Σ * b)
```

`Distributions.MvNormal`

— Type.`MvNormal`

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(sig)`

Construct a multivariate normal distribution with zero mean and covariance represented by `sig`

.

`MvNormal(mu, sig)`

Construct a multivariate normal distribution with mean `mu`

and covariance represented by `sig`

.

`MvNormal(d, sig)`

Construct a multivariate normal distribution of dimension `d`

, with zero mean, and an isotropic covariance matrix corresponding `abs2(sig)*I`

.

**Arguments**

`mu::Vector{T<:Real}`

: The mean vector.`d::Real`

: dimension of distribution.`sig`

: The covariance, which can in of either of the following forms (with`T<:Real`

):- subtype of
`AbstractPDMat`

, - symmetric matrix of type
`Matrix{T}`

, - vector of type
`Vector{T}`

: indicating a diagonal covariance as`diagm(abs2(sig))`

, - real-valued number: indicating an isotropic covariance matrix corresponding
`abs2(sig) * I`

.

- subtype of

**Note:** The constructor will choose an appropriate covariance form internally, so that special structure of the covariance can be exploited.

`Distributions.MvNormalCanon`

— Type.`MvNormalCanon`

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:

```
struct MvNormalCanon{P<:AbstractPDMat,V<:AbstractVector} <: 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{Axes} = MvNormalCanon{PDMat, Zeros{Float64,1}}
const ZeroMeanDiagNormalCanon{Axes} = MvNormalCanon{PDiagMat, Zeros{Float64,1}}
const ZeroMeanIsoNormalCanon{Axes} = MvNormalCanon{ScalMat, Zeros{Float64,1,Axes}}
```

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 by `J`

.

`MvNormalCanon(J)`

Construct a multivariate normal distribution with zero mean (thus zero potential vector) and precision matrix represented by `J`

.

`MvNormalCanon(d, J)`

Construct a multivariate normal distribution of dimension `d`

, with zero mean and an isotropic precision matrix corresponding `J*I`

.

**Arguments**

`d::Int`

: dimension of distribution`h::Vector{T<:Real}`

: the potential vector, of type`Vector{T}`

with`T<: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 as`diagm(J)`

, - a real number: indicating an isotropic precision matrix corresponding
`J*I`

.

- an instance of a subtype of

**Note:** `MvNormalCanon`

share the same set of methods as `MvNormal`

.

`Distributions.MvLogNormal`

— Type.`MvLogNormal(d::MvNormal)`

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.

`Distributions.Dirichlet`

— Type.`Dirichlet`

The Dirichlet distribution is often used as 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)
```

`Distributions.Product`

— Type.`Product <: MultivariateDistribution`

An N dimensional `MultivariateDistribution`

constructed from a vector of N independent `UnivariateDistribution`

s.

`Product(Uniform.(rand(10), 1)) # A 10-dimensional Product from 10 independent `Uniform` distributions.`

## Addition Methods

### AbstractMvNormal

In addition to the methods listed in the common interface above, we also provide the following methods for all multivariate distributions under the base type `AbstractMvNormal`

:

`Distributions.invcov`

— Method.`invcov(d::AbstractMvNormal)`

Return the inversed covariance matrix of d.

`Distributions.logdetcov`

— Method.`logdetcov(d::AbstractMvNormal)`

Return the log-determinant value of the covariance matrix.

`Distributions.sqmahal`

— Method.`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)`

with write the results to a pre-allocated array `r`

.

`Base.rand`

— Method.`rand(::AbstractRNG, ::Distributions.AbstractMvNormal)`

Sample a random vector from the provided multi-variate normal distribution.

### MvLogNormal

In addition to the methods listed in the common interface above, we also provide the following methods:

`Distributions.location`

— Method.`location(d::MvLogNormal)`

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

`Distributions.scale`

— Method.`scale(d::MvLogNormal)`

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

`Statistics.median`

— Method.`median(d::MvLogNormal)`

Return the median vector of the lognormal distribution. which is strictly smaller than the mean.

`StatsBase.mode`

— Method.`mode(d::MvLogNormal)`

Return the mode vector of the lognormal distribution, which is strictly smaller than the mean and median.

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.

`Distributions.location`

— Method.`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.

`Distributions.location!`

— Method.`location!{D<:AbstractMvLogNormal}(::Type{D},s::Symbol,m::AbstractVector,S::AbstractMatrix,μ::AbstractVector)`

Calculate the location vector (as above) and store the result in $μ$

`Distributions.scale`

— Method.`scale{D<:AbstractMvLogNormal}(::Type{D},s::Symbol,m::AbstractVector,S::AbstractMatrix)`

Calculate the scale parameter, as defined for the location parameter above.

`Distributions.scale!`

— Method.`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 `Σ`

.

`StatsBase.params`

— Method.`params{D<:AbstractMvLogNormal}(::Type{D},m::AbstractVector,S::AbstractMatrix)`

Return (scale,location) for a given mean and covariance

## Internal Methods (for creating you own multivariate distribution)

`Distributions._logpdf`

— Method.`_logpdf{T<:Real}(d::MultivariateDistribution, x::AbstractArray)`

Evaluate logarithm of pdf value for a given vector `x`

. This function need not perform dimension checking. Generally, one does not need to implement `pdf`

(or `_pdf`

) as fallback methods are provided in `src/multivariates.jl`

.

## Product distributions

`Distributions.product_distribution`

— Function.`product_distribution(dists::AbstractVector{<:UnivariateDistribution})`

Creates a multivariate product distribution `P`

from a vector of univariate distributions. Fallback is the `Product constructor`

, but specialized methods can be defined for distributions with a special multivariate product.

`product_distribution(dists::AbstractVector{<:Normal})`

Computes the multivariate Normal distribution obtained by stacking the univariate normal distributions. The result is a multivariate Gaussian with a diagonal covariance matrix.

Using `product_distribution`

is advised to construct product distributions. For some distributions, it constructs a special multivariate type.