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:
 At Mark 23: a and b were made optional; tail was removed from the interface

## Description

Let the vector random variable $X={\left({X}_{1},{X}_{2},\dots ,{X}_{n}\right)}^{\mathrm{T}}$ follow an $n$-dimensional multivariate Normal distribution with mean vector $\mu$ and $n$ by $n$ variance-covariance matrix $\Sigma$, then the probability density function, $f\left(X:\mu ,\Sigma \right)$, is given by
 $fX:μ,Σ = 2π - 1/2 n Σ -1/2 exp -12 X-μT Σ-1 X-μ .$
The lower tail probability is defined by:
 $PX1≤b1,…,Xn≤bn: μ ,Σ=∫-∞ b1⋯∫-∞ bnfX : μ ,Σ dXn⋯dX1.$
The upper tail probability is defined by:
 $PX1≥a1,…,Xn≥an:μ,Σ=∫a1∞⋯∫an∞fX:μ,ΣdXn⋯dX1.$
The central probability is defined by:
 $Pa1≤X1≤b1,…,an≤Xn≤bn: μ ,Σ=∫a1b1⋯∫anbnfX : μ ,Σ dXn⋯dX1.$
To evaluate the probability for $n\ge 3$, the probability density function of ${X}_{1},{X}_{2},\dots ,{X}_{n}$ is considered as the product of the conditional probability of ${X}_{1},{X}_{2},\dots ,{X}_{n-2}$ given ${X}_{n-1}$ and ${X}_{n}$ and the marginal bivariate Normal distribution of ${X}_{n-1}$ and ${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 $n-2$ dimensions. In the case of $n=3$, nag_quad_1d_fin_bad (d01aj) is used and for $n>3$ nag_quad_md_adapt (d01fc) is used.
To evaluate the probability for $n=1$ a direct call to nag_stat_prob_normal (g01ea) is made and for $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:     $\mathrm{xmu}\left({\mathbf{n}}\right)$ – double array
$\mu$, the mean vector of the multivariate Normal distribution.
2:     $\mathrm{sig}\left(\mathit{ldsig},{\mathbf{n}}\right)$ – double array
ldsig, the first dimension of the array, must satisfy the constraint $\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:     $\mathrm{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$, the number of dimensions.
Constraint: $1\le {\mathbf{n}}\le 10$.
2:     $\mathrm{a}\left({\mathbf{n}}\right)$ – double array
If upper tail or central probablilities are to be returned, a should supply the lower bounds, ${a}_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,n$.
3:     $\mathrm{b}\left({\mathbf{n}}\right)$ – double array
If lower tail or central probablilities are to be returned, b should supply the upper bounds, ${b}_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,n$.
4:     $\mathrm{tol}$ – double scalar
Default: $0.0001$
If $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 Accuracy.
If $n=1$, tol is not referenced.
Constraint: if ${\mathbf{n}}>1$, ${\mathbf{tol}}>0.0$.

### Output Parameters

1:     $\mathrm{result}$ – double scalar
The result of the function.
2:     $\mathrm{ifail}$int64int32nag_int scalar
${\mathbf{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}}$, ${\mathbf{2}}$ or ${\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.

${\mathbf{ifail}}=1$
Constraint: $1\le {\mathbf{n}}\le 10$.
Constraint: $\mathit{ldsig}\ge {\mathbf{n}}$.
Constraint: ${\mathbf{tol}}>0.0$.
${\mathbf{ifail}}=2$
On entry, the $_$ value in b is less than or equal to the corresponding value in a.
${\mathbf{ifail}}=3$
On entry, sig is not positive definite.
W  ${\mathbf{ifail}}=4$
Full accuracy not achieved, relative accuracy $\text{}=_$. A larger value of tol can be tried or the length of the workspace increased. The returned value is an approximation to the required result.
W  ${\mathbf{ifail}}=5$
Accuracy requested by tol is too strict: ${\mathbf{tol}}=_$. Round-off error has prevented the requested accuracy from being achieved; a larger value of tol can be tried. The returned value will be an approximation to the required result.
${\mathbf{ifail}}=-99$
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

## 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 $n-2$ dimensions over which the numerical integration takes place; these cut-off points are given by ${\Phi }^{-1}\left({\mathbf{tol}}/\left(10×n\right)\right)$, where ${\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 (${b}_{i}-{a}_{i}$, for $\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$ so that the largest ranges of integration are for ${X}_{n-1}$ and ${X}_{n}$.

## Example

This example reads in the mean and covariance matrix for a multivariate Normal distribution and computes and prints the associated central probability.
```function g01hb_example

fprintf('g01hb example results\n\n');

a   = [-2;   -2;    -2;    -2  ];
b   = [ 2;    2;     2;     2  ];
xmu = [ 0;    0;     0;     0  ];
sig = [ 1.0,  0.9,   0.9,   0.9;
0.9,  1.0,   0.9,   0.9;
0.9,  0.9,   1.0,   0.9;
0.9,  0.9,   0.9,   1.0];

[p, ifail] = g01hb(xmu, sig, 'a', a, 'b', b);

fprintf('Multivariate Normal probability = %7.4f\n', p);

```
```g01hb example results

Multivariate Normal probability =  0.9142
```