nag_multi_normal (g01hbc) (PDF version)
g01 Chapter Contents
g01 Chapter Introduction
NAG C Library Manual

NAG Library Function Document

nag_multi_normal (g01hbc)

+ Contents

    1  Purpose
    7  Accuracy

1  Purpose

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

2  Specification

#include <nag.h>
#include <nagg01.h>
double  nag_multi_normal (Nag_TailProbability tail, Integer n, const double a[], const double b[], const double mean[], const double sigma[], Integer tdsig, double tol, Integer maxpts, NagError *fail)

3  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_bivariate_normal_dist (g01hac) and numerical integration is then used over the remaining n-2 dimensions. In the case of n=3, nag_1d_quad_gen_1 (d01sjc) is used and for n>3 nag_multid_quad_adapt_1 (d01wcc) is used.
To evaluate the probability for n=1 a direct call to nag_prob_normal (g01eac) is made and for n=2 calls to nag_bivariate_normal_dist (g01hac) are made.

4  References

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

5  Arguments

1:     tailNag_TailProbabilityInput
On entry: indicates which probability is to be returned.
tail=Nag_LowerTail
The lower tail probability is returned.
tail=Nag_UpperTail
The upper tail probability is returned.
tail=Nag_Central
The central probability is returned.
Constraint: tail=Nag_LowerTail, Nag_UpperTail or Nag_Central.
2:     nIntegerInput
On entry: n, the number of dimensions.
Constraint: 1n10.
3:     a[n]const doubleInput
On entry: if tail=Nag_Central or Nag_UpperTail, the lower bounds, ai, for i=1,2,,n.
If tail=Nag_LowerTail, a is not referenced.
4:     b[n]const doubleInput
On entry: if tail=Nag_Central or Nag_LowerTail, the upper bounds, bi, for i=1,2,,n.
If tail=Nag_UpperTail b, is not referenced.
Constraint: if tail=Nag_Central, a[i-1]<b[i-1], for i=1,2,,n.
5:     mean[n]const doubleInput
On entry: μ, the mean vector of the multivariate Normal distribution.
6:     sigma[n×tdsig]const doubleInput
Note: the i,jth element of the matrix is stored in sigma[i-1×tdsig+j-1].
On entry: Σ, the variance-covariance matrix of the multivariate Normal distribution. Only the lower triangle is referenced.
Constraint: Σ must be positive definite.
7:     tdsigIntegerInput
On entry: the stride separating matrix column elements in the array sigma.
Constraint: tdsign.
8:     toldoubleInput
On entry: 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 Section 7.
If n=1, tol is not referenced.
Suggested value: tol=0.0001.
Constraint: if n>1, tol>0.0.
9:     maxptsIntegerInput
On entry: the maximum number of sub-intervals or integrand evaluations.
If n=3 , then the maximum number of sub-intervals used by nag_1d_quad_gen_1 (d01sjc) is maxpts/4. Note however increasing maxpts above 1000 will not increase the maximum number of sub-intervals above 250.
If n>3  the maximum number of integrand evaluations used by nag_multid_quad_adapt_1 (d01wcc) is α (maxpts/ n-1 ), where α = 2 n-2 + 2 n-2 2 + 2 n-2 + 1 .
If n=1  or 2, then maxpts will not be used.
Suggested value: 2000 if n>3  and 1000 if n=3 .
Constraint: if n3 , maxpts 4 × n .
10:   failNagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

6  Error Indicators and Warnings

NE_2_INT_ARG_LT
On entry, tdsig=value and n=value.
Constraint: tdsign.
NE_2_REAL_ARRAYS_CONS
On entry, the value value in b is less than or equal to the corresponding value in a.
NE_ACC
Full accuracy not achieved, relative accuracy =value.
NE_ALLOC_FAIL
Dynamic memory allocation failed.
NE_BAD_PARAM
On entry, argument value had an illegal value.
NE_INT_ARG_CONS
On entry, maxpts=value and n=value.
Constraint: if n3 , maxpts 4 × n .
On entry, n=value.
Constraint: 1n10.
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
NE_POS_DEF
On entry, sigma is not positive definite.
NE_REAL_ARG_CONS
On entry, tol=value.
Constraint: tol>0.0.
NE_ROUND_OFF
Accuracy requested by tol is too strict: tol=value.

7  Accuracy

The accuracy should be as specified by tol. When on exit fail.code= NE_ACC 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.

8  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.

9  Example

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

9.1  Program Text

Program Text (g01hbce.c)

9.2  Program Data

Program Data (g01hbce.d)

9.3  Program Results

Program Results (g01hbce.r)


nag_multi_normal (g01hbc) (PDF version)
g01 Chapter Contents
g01 Chapter Introduction
NAG C Library Manual

© The Numerical Algorithms Group Ltd, Oxford, UK. 2012