cdfMvnce¶

Purpose¶

Computes the complement (upper tail) of the multivariate Normal cumulative distribution function with error management.

Format¶

{ y, err, retcode } = cdfMvnce(ctl, x, corr, nonc)¶

Parameters:

ctl (struct) –
instance of a cdfmControl structure with members

ctl.maxEvaluations

scalar, maximum number of evaluations.

ctl.absErrorTolerance

scalar, absolute error tolerance.

ctl.relErrorTolerance

scalar, error tolerance.
x (NxK matrix) – Lower limits at which to evaluate the complement of the multivariate normal cumulative distribution function. x must have K columns–one for each variable. If x has more than one row, each row will be treated as a separate set of upper limits.
corr (KxK matrix) – correlation matrix.
nonc (Kx1 vector) – non-centrality vector.

Returns:

p (Nx1 vector) – \(Pr(X ≥ x|corr, nonc)\). The probability in the upper tail of the multivariate normal cumulative distribution function for each corresponding set of limits in x.
err (Nx1 vector) – estimates of absolute error.

retcode (Nx1 vector) –

return codes.

0	normal completion with \(err < ctl.absErrorTolerance\).
1	\(err > ctl.absErrorTolerance\) and ctl.maxEvaluations exceeded; increase ctl.maxEvaluations to decrease error.
2	\(K > 100\) or \(K < 1\)
3	R not positive semi-definite.
missing	R not properly defined.

Examples¶

Uncorrelated variables¶

// Lower limits of integration for K dimensional multivariate distribution
x = { 0  0 };

/*
** Identity matrix, indicates
** zero correlation between variables
*/
corr = { 1 0,
         0 1 };

// Define non-centrality parameter for each variable
nonc  = { 0, 0};

// Define control structure
struct cdfmControl ctl;
ctl = cdfmControlCreate();

/*
** Calculate cumulative probability of
** both variables being ≥ 0
*/
{ p, err, retcode } = cdfMvnce(ctl, x, corr, nonc);

/*
** Calculate joint probability of two
** variables with zero correlation,
** both, being ≥ 0
*/
p2 = cdfnc(0) .* cdfnc(0);

After the above code, both p and p2 should be equal to 0.25.

\[\Phi = P(0 \leq X_1 < \infty \text{ and } 0 \leq X_2 < \infty) \approx 0.25.\]

Compute the upper tail of multivariate normal cdf at 3 separate pairs of lower limits¶

/*
** Lower limits of integration
** x1 ≥ -1 and x2 ≥ -1.1
** x1 ≥  0 and x2 ≥ 0.1
** x1 ≥  1 and x2 ≥ 1.1
*/
x = {  -1   -1.1,
        0    0.1,
        1    1.1 };

// Correlation matrix
corr = {   1  0.31,
     0.31     1 };

// Define non-centrality parameter for each variable
nonc  = { 0, 0 };

// Define control structure
struct cdfmControl ctl;
ctl = cdfmControlCreate();

/*
** Calculate cumulative probability of
** each pair of lower limits
*/
{ p, err, retcode }  = cdfMvnce(ctl, x, corr, nonc);

After the above code, p should equal:

74642007
27999181
04074138

which means that:

\[\begin{split}P(x_1 \geq -1 \text{ and } x_2 \geq -1.1) = 0.7464\\ P(x_1 \geq +0 \text{ and } x_2 \geq +0.1) = 0.2800\\ P(x_1 \geq 1 \text{ and } x_2 \geq 1.1) = 0.0407\end{split}\]

Compute the upper tail of noncentral multivariate normal cdf¶

/* Lower limits of integration
** x1 ≥ -1 and x2 ≥ -1.1
** x1 ≥  0 and  x2 ≥ 0.1
** x1 ≥  1 and x2 ≥ 1.1
*/
x = { -1   -1.1,
       0    0.1,
       1    1.1 };

// Correlation matrix
corr = {   1  0.31,
        0.31     1 };

// Define non-centrality vector, Kx1
// vector, one for each variable
nonc  = { 1, -2.5 };

// Define control structure
struct cdfmControl ctl;
ctl = cdfmControlCreate();

/*
** Calculate cumulative probability of
** each pair of lower limits
*/
{ p, err, retcode } = cdfMvnce(ctl, x, corr, nonc);

After the above code, p should equal:

08046686
00455354
00014231

which means with non-central vector, the multivariate normal cdf are:

\[\begin{split}P(x_1 \geq -1 \text{ and } x_2 \geq -1.1) = 0.0805\\ P(x_1 \geq +0 \text{ and } x_2 \geq +0.1) = 0.0046\\ P(x_1 \geq 1 \text{ and } x_2 \geq 1.1) = 0.0001\end{split}\]

Remarks¶

The cdfMvnce() evaluates the upper tail of MVN integral, where \(1\leqslant i \leqslant N\) For the non-central MVN, we have where \(z\) denotes \(K\) -dimensional multivariate normal distribution, \(\delta\) denotes the \(K \times 1\) non-centrality vector with \(-\infty<\:\ \delta_k <\:\ \infty\).
The correlation matrix \(R\) is defined by \(\Sigma = DRD\), where \(D\) denotes the diagonal matrix which has the square roots of the diagonal entries for covariance matrix \(\Sigma\) on its diagonal.

References¶

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, 63:361-378, 1999.
Genz, A., ‘’Numerical computation of multivariate normal probabilities’’, Journal of Computational and Graphical Statistics, 1:141-149, 1992.

ctl.maxEvaluations	scalar, maximum number of evaluations.
ctl.absErrorTolerance	scalar, absolute error tolerance.
ctl.relErrorTolerance	scalar, error tolerance.