# MultivariateNormal: Multivariate Normal Distribution Class In distr6: The Complete R6 Probability Distributions Interface

## Description

Mathematical and statistical functions for the Multivariate Normal distribution, which is commonly used to generalise the Normal distribution to higher dimensions, and is commonly associated with Gaussian Processes.

## Details

The Multivariate Normal distribution parameterised with mean, μ, and covariance matrix, Σ, is defined by the pdf,

f(x_1,...,x_k) = (2 * π)^{-k/2}det(Σ)^{-1/2}exp(-1/2(x-μ)^TΣ^{-1}(x-μ))

for μ ε R^{k} and Σ ε R^{k x k}.

Sampling is performed via the Cholesky decomposition using chol.

Number of variables cannot be changed after construction.

## Value

Returns an R6 object inheriting from class SDistribution.

## Distribution support

The distribution is supported on the Reals and only when the covariance matrix is positive-definite.

## Default Parameterisation

MultiNorm(mean = rep(0, 2), cov = c(1, 0, 0, 1))

## Omitted Methods

`cdf` and `quantile` are omitted as no closed form analytic expression could be found, decorate with `FunctionImputation` for a numerical imputation.

N/A

## Super classes

`distr6::Distribution` -> `distr6::SDistribution` -> `MultivariateNormal`

## Public fields

`name`

Full name of distribution.

`short_name`

Short name of distribution for printing.

`description`

Brief description of the distribution.

## Active bindings

`properties`

Returns distribution properties, including skewness type and symmetry.

## Methods

#### Public methods

Inherited methods

#### Method `new()`

Creates a new instance of this R6 class. Number of variables cannot be changed after construction.

##### Usage
```MultivariateNormal\$new(
mean = rep(0, 2),
cov = c(1, 0, 0, 1),
prec = NULL,
decorators = NULL
)```
##### Arguments
`mean`

`(numeric())`
Vector of means, defined on the Reals.

`cov`

`(matrix()|vector())`
Covariance of the distribution, either given as a matrix or vector coerced to a matrix via `matrix(cov, nrow = K, byrow = FALSE)`. Must be semi-definite.

`prec`

`(matrix()|vector())`
Precision of the distribution, inverse of the covariance matrix. If supplied then `cov` is ignored. Given as a matrix or vector coerced to a matrix via `matrix(cov, nrow = K, byrow = FALSE)`. Must be semi-definite.

`decorators`

`(character())`
Decorators to add to the distribution during construction.

#### Method `mean()`

The arithmetic mean of a (discrete) probability distribution X is the expectation

E_X(X) = ∑ p_X(x)*x

with an integration analogue for continuous distributions.

##### Usage
`MultivariateNormal\$mean(...)`
`...`

Unused.

#### Method `mode()`

The mode of a probability distribution is the point at which the pdf is a local maximum, a distribution can be unimodal (one maximum) or multimodal (several maxima).

##### Usage
`MultivariateNormal\$mode(which = "all")`
##### Arguments
`which`

`(character(1) | numeric(1)`
Ignored if distribution is unimodal. Otherwise `"all"` returns all modes, otherwise specifies which mode to return.

#### Method `variance()`

The variance of a distribution is defined by the formula

var_X = E[X^2] - E[X]^2

where E_X is the expectation of distribution X. If the distribution is multivariate the covariance matrix is returned.

##### Usage
`MultivariateNormal\$variance(...)`
`...`

Unused.

#### Method `entropy()`

The entropy of a (discrete) distribution is defined by

- ∑ (f_X)log(f_X)

where f_X is the pdf of distribution X, with an integration analogue for continuous distributions.

##### Usage
`MultivariateNormal\$entropy(base = 2, ...)`
##### Arguments
`base`

`(integer(1))`
Base of the entropy logarithm, default = 2 (Shannon entropy)

`...`

Unused.

#### Method `mgf()`

The moment generating function is defined by

mgf_X(t) = E_X[exp(xt)]

where X is the distribution and E_X is the expectation of the distribution X.

##### Usage
`MultivariateNormal\$mgf(t, ...)`
##### Arguments
`t`

`(integer(1))`
t integer to evaluate function at.

`...`

Unused.

#### Method `cf()`

The characteristic function is defined by

cf_X(t) = E_X[exp(xti)]

where X is the distribution and E_X is the expectation of the distribution X.

##### Usage
`MultivariateNormal\$cf(t, ...)`
##### Arguments
`t`

`(integer(1))`
t integer to evaluate function at.

`...`

Unused.

#### Method `pgf()`

The probability generating function is defined by

pgf_X(z) = E_X[exp(z^x)]

where X is the distribution and E_X is the expectation of the distribution X.

##### Usage
`MultivariateNormal\$pgf(z, ...)`
##### Arguments
`z`

`(integer(1))`
z integer to evaluate probability generating function at.

`...`

Unused.

#### Method `getParameterValue()`

Returns the value of the supplied parameter.

##### Usage
`MultivariateNormal\$getParameterValue(id, error = "warn")`
##### Arguments
`id`

`character()`
id of parameter support to return.

`error`

`(character(1))`
If `"warn"` then returns a warning on error, otherwise breaks if `"stop"`.

#### Method `setParameterValue()`

Sets the value(s) of the given parameter(s).

##### Usage
```MultivariateNormal\$setParameterValue(
...,
lst = list(...),
error = "warn",
resolveConflicts = FALSE
)```
##### Arguments
`...`

`ANY`
Named arguments of parameters to set values for. See examples.

`lst`

`(list(1))`
Alternative argument for passing parameters. List names should be parameter names and list values are the new values to set.

`error`

`(character(1))`
If `"warn"` then returns a warning on error, otherwise breaks if `"stop"`.

`resolveConflicts`

`(logical(1))`
If `FALSE` (default) throws error if conflicting parameterisations are provided, otherwise automatically resolves them by removing all conflicting parameters.

#### Method `clone()`

The objects of this class are cloneable with this method.

##### Usage
`MultivariateNormal\$clone(deep = FALSE)`
##### Arguments
`deep`

Whether to make a deep clone.

## References

McLaughlin, M. P. (2001). A compendium of common probability distributions (pp. 2014-01). Michael P. McLaughlin.

Gentle, J.E. (2009). Computational Statistics. Statistics and Computing. New York: Springer. pp. 315–316. doi:10.1007/978-0-387-98144-4. ISBN 978-0-387-98143-7.

Other continuous distributions: `Arcsine`, `BetaNoncentral`, `Beta`, `Cauchy`, `ChiSquaredNoncentral`, `ChiSquared`, `Dirichlet`, `Erlang`, `Exponential`, `FDistributionNoncentral`, `FDistribution`, `Frechet`, `Gamma`, `Gompertz`, `Gumbel`, `InverseGamma`, `Laplace`, `Logistic`, `Loglogistic`, `Lognormal`, `Normal`, `Pareto`, `Poisson`, `Rayleigh`, `ShiftedLoglogistic`, `StudentTNoncentral`, `StudentT`, `Triangular`, `Uniform`, `Wald`, `Weibull`
Other multivariate distributions: `Dirichlet`, `EmpiricalMV`, `Multinomial`