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:

0.74642007
0.27999181
0.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:

0.08046686
0.00455354
0.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#

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

  2. Genz, A., ‘’Numerical computation of multivariate normal probabilities’’, Journal of Computational and Graphical Statistics, 1:141-149, 1992.

See also

Functions cdfMvn2e(), cdfMvnce(), cdfMvte()

On this page