hide long namesshow long names
hide short namesshow short names
Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

NAG Toolbox: nag_stat_prob_multi_normal (g01hb)

 Contents

    1  Purpose
    2  Syntax
    7  Accuracy
    9  Example

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 = X1,X2,,XnT  follow an n-dimensional multivariate Normal distribution with mean vector μ and n by n variance-covariance matrix Σ, then the probability density function, fX:μ,Σ, is given by
fX:μ,Σ = 2π - 1/2 n Σ -1/2 exp -12 X-μT Σ-1 X-μ .  
The lower tail probability is defined by:
PX1b1,,Xnbn: μ ,Σ=- b1- bnfX : μ ,Σ dXndX1.  
The upper tail probability is defined by:
PX1a1,,Xnan:μ,Σ=a1anfX:μ,ΣdXndX1.  
The central probability is defined by:
Pa1X1b1,,anXnbn: μ ,Σ=a1b1anbnfX : μ ,Σ dXndX1.  
To evaluate the probability for n3, the probability density function of X1,X2,,Xn is considered as the product of the conditional probability of X1,X2,,Xn-2 given Xn-1 and Xn and the marginal bivariate Normal distribution of Xn-1 and Xn. 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:     xmun – double array
μ, the mean vector of the multivariate Normal distribution.
2:     sigldsign – double array
ldsig, the first dimension of the array, must satisfy the constraint ldsign.
Σ, the variance-covariance matrix of the multivariate Normal distribution. Only the lower triangle is referenced.
Constraint: Σ 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, the number of dimensions.
Constraint: 1n10.
2:     an – double array
If upper tail or central probablilities are to be returned, a should supply the lower bounds, ai, for i=1,2,,n.
3:     bn – double array
If lower tail or central probablilities are to be returned, b should supply the upper bounds, bi, for i=1,2,,n.
4:     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 n>1, tol>0.0.

Output Parameters

1:     result – double scalar
The result of the function.
2:     ifail int64int32nag_int scalar
ifail=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 ifail=1, 2 or 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
Constraint: 1n10.
Constraint: ldsign.
Constraint: tol>0.0.
   ifail=2
On entry, the _ value in b is less than or equal to the corresponding value in a.
   ifail=3
On entry, sig is not positive definite.
W  ifail=4
Full accuracy not achieved, relative accuracy =_. 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  ifail=5
Accuracy requested by tol is too strict: 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.
   ifail=-99
An unexpected error has been triggered by this routine. Please contact NAG.
   ifail=-399
Your licence key may have expired or may not have been installed correctly.
   ifail=-999
Dynamic memory allocation failed.

Accuracy

The accuracy should be as specified by tol. When on exit ifail=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 Φ-1tol/10×n, where Φ-1 is the inverse univariate Normal distribution function.

Further Comments

The time taken is related to the number of dimensions, the range over which the integration takes place (bi-ai, for i=1,2,,n) and the value of Σ 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 Xn-1 and Xn.

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

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2015