# mvncdf

Multivariate normal cumulative distribution function

## Syntax

`y = mvncdf(X)y = mvncdf(X,mu,SIGMA)y = mvncdf(xl,xu,mu,SIGMA)[y,err] = mvncdf(...)[...] = mvncdf(...,options)`

## Description

`y = mvncdf(X)` returns the cumulative probability of the multivariate normal distribution with zero mean and identity covariance matrix, evaluated at each row of `X`. Rows of the n-by-d matrix `X` correspond to observations or points, and columns correspond to variables or coordinates. `y` is an n-by-`1` vector.

`y = mvncdf(X,mu,SIGMA)` returns the cumulative probability of the multivariate normal distribution with mean `mu` and covariance `SIGMA`, evaluated at each row of `X`. `mu` is a `1`-by-d vector, and `SIGMA` is a d-by-d symmetric, positive definite matrix. `mu` can also be a scalar value, which `mvncdf` replicates to match the size of `X`. If the covariance matrix is diagonal, containing variances along the diagonal and zero covariances off the diagonal, `SIGMA` may also be specified as a `1`-by-d vector containing just the diagonal. Pass in the empty matrix `[]` for `mu` to use as its default value when you want to only specify `SIGMA`.

The multivariate normal cumulative probability at `X` is defined as the probability that a random vector `V`, distributed as multivariate normal, will fall within the semi-infinite rectangle with upper limits defined by `X`, for example, `Pr{V(1)`` X(1),V(2) `` X(2),...,V(d)`` X(d)`}.

`y = mvncdf(xl,xu,mu,SIGMA)` returns the multivariate normal cumulative probability evaluated over the rectangle with lower and upper limits defined by `xl` and `xu`, respectively.

`[y,err] = mvncdf(...)` returns an estimate of the error in `y`. For bivariate and trivariate distributions, `mvncdf` uses adaptive quadrature on a transformation of the t density, based on methods developed by Drezner and Wesolowsky and by Genz, as described in the references. The default absolute error tolerance for these cases is `1e-8`. For four or more dimensions, `mvncdf` uses a quasi-Monte Carlo integration algorithm based on methods developed by Genz and Bretz, as described in the references. The default absolute error tolerance for these cases is `1e-4`.

`[...] = mvncdf(...,options)` specifies control parameters for the numerical integration used to compute `y`. This argument can be created by a call to `statset`. Choices of `statset` parameters:

• `'TolFun'` — Maximum absolute error tolerance. Default is `1e-8` when d < 4, or `1e-4` when d ≥ 4.

• `'MaxFunEvals'` — Maximum number of integrand evaluations allowed when d ≥ 4. Default is `1e7`. `'MaxFunEvals'` is ignored when d < 4.

• `'Display'` — Level of display output. Choices are `'off'` (the default), `'iter'`, and `'final'`. `'Display'` is ignored when d < 4.

## Examples

collapse all

### Compute the Multivariate Normal cdf

Compute and plot the cdf of a multivariate normal distribution with parameters `mu = [1 -1]` and `SIGMA = [.9 .4; .4 .3]`.

```mu = [1 -1]; SIGMA = [.9 .4; .4 .3]; figure; [X1,X2] = meshgrid(linspace(-1,3,25)',linspace(-3,1,25)'); X = [X1(:) X2(:)]; p = mvncdf(X,mu,SIGMA); surf(X1,X2,reshape(p,25,25)); ```

## References

[1] Drezner, Z. "Computation of the Trivariate Normal Integral." Mathematics of Computation. Vol. 63, 1994, pp. 289–294.

[2] Drezner, Z., and G. O. Wesolowsky. "On the Computation of the Bivariate Normal Integral." Journal of Statistical Computation and Simulation. Vol. 35, 1989, pp. 101–107.

[3] Genz, A. "Numerical Computation of Rectangular Bivariate and Trivariate Normal and t Probabilities." Statistics and Computing. Vol. 14, No. 3, 2004, pp. 251–260.

[4] Genz, A., and F. Bretz. "Numerical Computation of Multivariate t Probabilities with Application to Power Calculation of Multiple Contrasts." Journal of Statistical Computation and Simulation. Vol. 63, 1999, pp. 361–378.

[5] Genz, A., and F. Bretz. "Comparison of Methods for the Computation of Multivariate t Probabilities." Journal of Computational and Graphical Statistics. Vol. 11, No. 4, 2002, pp. 950–971.