Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_stat_prob_multi_normal (g01hb)

## Purpose

nag_stat_prob_multi_normal (g01hb) returns the upper tail, lower tail or central probability associated with a multivariate Normal distribution of up to ten dimensions.

## Syntax

[result, ifail] = g01hb(xmu, sig, 'n', n, 'a', a, 'b', b, 'tol', tol)
[result, ifail] = nag_stat_prob_multi_normal(xmu, sig, 'n', n, 'a', a, 'b', b, 'tol', tol)
Note: the interface to this routine has changed since earlier releases of the toolbox:
Mark 23: a and b now optional, tail dropped from interface
.

## Description

Let the vector random variable X = (X1,X2,,Xn)T $X={\left({X}_{1},{X}_{2},\dots ,{X}_{n}\right)}^{\mathrm{T}}$ follow an n$n$-dimensional multivariate Normal distribution with mean vector μ$\mu$ and n$n$ by n$n$ variance-covariance matrix Σ$\Sigma$, then the probability density function, f(X : μ,Σ)$f\left(X:\mu ,\Sigma \right)$, is given by
 f(X : μ,Σ) = (2π) − (1 / 2) n |Σ| − 1 / 2 exp( − (1/2)(X − μ)TΣ − 1(X − μ)) . $f(X:μ,Σ) = (2π) - (1/2) n |Σ| -1/2 exp( -12 (X-μ)T Σ-1 (X-μ) ) .$
The lower tail probability is defined by:
 b1 bn P(X1 ≤ b1, … ,Xn ≤ bn : μ ,Σ) = ∫ ⋯ ∫ f(X : μ ,Σ )dXn ⋯ dX1. − ∞ − ∞
$P(X1≤b1,…,Xn≤bn: μ ,Σ)=∫-∞ b1⋯∫-∞ bnf(X : μ ,Σ) dXn⋯dX1.$
The upper tail probability is defined by:
 ∞ ∞ P(X1 ≥ a1, … ,Xn ≥ an : μ,Σ) = ∫ ⋯ ∫ f(X : μ,Σ)dXn ⋯ dX1. a1 an
$P(X1≥a1,…,Xn≥an:μ,Σ)=∫a1∞⋯∫an∞f(X:μ,Σ)dXn⋯dX1.$
The central probability is defined by:
 b1 bn P(a1 ≤ X1 ≤ b1, … ,an ≤ Xn ≤ bn : μ ,Σ ) = ∫ ⋯ ∫ f(X : μ ,Σ )dXn ⋯ dX1. a1 an
$P(a1≤X1≤b1,…,an≤Xn≤bn: μ ,Σ)=∫a1b1⋯∫anbnf(X : μ ,Σ) dXn⋯dX1.$
To evaluate the probability for n3$n\ge 3$, the probability density function of X1,X2,,Xn${X}_{1},{X}_{2},\dots ,{X}_{n}$ is considered as the product of the conditional probability of X1,X2,,Xn2${X}_{1},{X}_{2},\dots ,{X}_{n-2}$ given Xn1${X}_{n-1}$ and Xn${X}_{n}$ and the marginal bivariate Normal distribution of Xn1${X}_{n-1}$ and Xn${X}_{n}$. The bivariate Normal probability can be evaluated as described in nag_stat_prob_bivariate_normal (g01ha) and numerical integration is then used over the remaining n2$n-2$ dimensions. In the case of n = 3$n=3$, nag_quad_1d_fin_bad (d01aj) is used and for n > 3$n>3$ nag_quad_md_adapt (d01fc) is used.
To evaluate the probability for n = 1$n=1$ a direct call to nag_stat_prob_normal (g01ea) is made and for n = 2$n=2$ calls to nag_stat_prob_bivariate_normal (g01ha) are made.

## References

Kendall M G and Stuart A (1969) The Advanced Theory of Statistics (Volume 1) (3rd Edition) Griffin

## Parameters

### Compulsory Input Parameters

1:     xmu(n) – double array
n, the dimension of the array, must satisfy the constraint 1n10$1\le {\mathbf{n}}\le 10$.
μ$\mu$, the mean vector of the multivariate Normal distribution.
2:     sig(ldsig,n) – double array
ldsig, the first dimension of the array, must satisfy the constraint ldsign$\mathit{ldsig}\ge {\mathbf{n}}$.
Σ$\Sigma$, the variance-covariance matrix of the multivariate Normal distribution. Only the lower triangle is referenced.
Constraint: Σ$\Sigma$ must be positive definite.

### Optional Input Parameters

1:     n – int64int32nag_int scalar
Default: The dimension of the arrays a, b, xmu and the first dimension of the array sig and the second dimension of the array sig. (An error is raised if these dimensions are not equal.)
n$n$, the number of dimensions.
Constraint: 1n10$1\le {\mathbf{n}}\le 10$.
2:     a(n) – double array
If upper tail or central probablilities are to be returned, a should supply the lower bounds, ai${a}_{\mathit{i}}$, for i = 1,2,,n$\mathit{i}=1,2,\dots ,n$.
3:     b(n) – double array
If lower tail or central probablilities are to be returned, b should supply the upper bounds, bi${b}_{\mathit{i}}$, for i = 1,2,,n$\mathit{i}=1,2,\dots ,n$.
4:     tol – double scalar
If n > 2$n>2$ the relative accuracy required for the probability, and if the upper or the lower tail probability is requested then tol is also used to determine the cut-off points, see Section [Accuracy].
If n = 1$n=1$, tol is not referenced.
Default: 0.0001$0.0001$
Constraint: if n > 1${\mathbf{n}}>1$, tol > 0.0${\mathbf{tol}}>0.0$.

### Input Parameters Omitted from the MATLAB Interface

tail ldsig wk lwk

### Output Parameters

1:     result – double scalar
The result of the function.
2:     ifail – int64int32nag_int scalar
${\mathrm{ifail}}={\mathbf{0}}$ unless the function detects an error (see [Error Indicators and Warnings]).

## Error Indicators and Warnings

Note: nag_stat_prob_multi_normal (g01hb) may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the function:
If on exit ${\mathbf{ifail}}={\mathbf{1}}$, 2${\mathbf{2}}$ or 3${\mathbf{3}}$, then nag_stat_prob_multi_normal (g01hb) returns zero.

Cases prefixed with W are classified as warnings and do not generate an error of type NAG:error_n. See nag_issue_warnings.

ifail = 1${\mathbf{ifail}}=1$
 On entry, n < 1${\mathbf{n}}<1$, or n > 10${\mathbf{n}}>10$, or ldsig < n$\mathit{ldsig}<{\mathbf{n}}$, or tail ≠ 'L'$\mathit{tail}\ne \text{'L'}$, 'U'$\text{'U'}$ or 'C'$\text{'C'}$, or n > 1${\mathbf{n}}>1$ and tol ≤ 0.0${\mathbf{tol}}\le 0.0$, or lwk is too small.
ifail = 2${\mathbf{ifail}}=2$
 On entry, tail = 'C'$\mathit{tail}=\text{'C'}$ and a(i) ≥ b(i)${\mathbf{a}}\left(i\right)\ge {\mathbf{b}}\left(i\right)$, for some i = 1,2, … ,n$i=1,2,\dots ,n$.
ifail = 3${\mathbf{ifail}}=3$
 On entry, Σ$\Sigma$ is not positive definite, i.e., is not a correct variance-covariance matrix.
W ifail = 4${\mathbf{ifail}}=4$
The requested accuracy has not been achieved, a larger value of tol should be tried or the length of the workspace should be increased. The returned value will be an approximation to the required result.
W ifail = 5${\mathbf{ifail}}=5$
Round-off error prevents the requested accuracy from being achieved; a larger value of tol should be tried. The returned value will be an approximation to the required result. This error will only occur if n = 3$n=3$.

## Accuracy

The accuracy should be as specified by tol. When on exit ${\mathbf{ifail}}={\mathbf{4}}$ the approximate accuracy achieved is given in the error message. For the upper and lower tail probabilities the infinite limits are approximated by cut-off points for the n2$n-2$ dimensions over which the numerical integration takes place; these cut-off points are given by Φ1(tol / (10 × n))${\Phi }^{-1}\left({\mathbf{tol}}/\left(10×n\right)\right)$, where Φ1${\Phi }^{-1}$ is the inverse univariate Normal distribution function.

The time taken is related to the number of dimensions, the range over which the integration takes place (biai${b}_{i}-{a}_{i}$, for i = 1,2,,n$\mathit{i}=1,2,\dots ,n$) and the value of Σ$\Sigma$ as well as the accuracy required. As the numerical integration does not take place over the last two dimensions speed may be improved by arranging X$X$ so that the largest ranges of integration are for Xn1${X}_{n-1}$ and Xn${X}_{n}$.

## Example

```function nag_stat_prob_multi_normal_example
a = [-2;
-2;
-2;
-2];
b = [2;
2;
2;
2];
xmu = [0;
0;
0;
0];
sig = [1, 0.9, 0.9, 0.9;
0.9, 1, 0.9, 0.9;
0.9, 0.9, 1, 0.9;
0.9, 0.9, 0.9, 1];
[result, ifail] = nag_stat_prob_multi_normal(xmu, sig, 'a', a, 'b', b)
```
```

result =

0.9142

ifail =

0

```
```function g01hb_example
a = [-2;
-2;
-2;
-2];
b = [2;
2;
2;
2];
xmu = [0;
0;
0;
0];
sig = [1, 0.9, 0.9, 0.9;
0.9, 1, 0.9, 0.9;
0.9, 0.9, 1, 0.9;
0.9, 0.9, 0.9, 1];
[result, ifail] = g01hb(xmu, sig, 'a', a, 'b', b)
```
```

result =

0.9142

ifail =

0

```