cdfMvn2e

Purpose

Computes the multivariate normal cumulative distribution function with error management over the range \([a,b]\).

Format

{ y, err, retcode } = cdfMvn2e(ctl, l_lim, u_lim, 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.
  • l_lim (NxK matrix) – lower limits.
  • u_lim (NxK matrix) – upper limits.
  • corr (KxK matrix) – correlation matrix.
  • nonc (Kx1 vector) – non-centrality vector.
Returns:
  • p (Nx1 vector) – Each element in p is the cumulative distribution function of the multivariate normal distribution for each corresponding columns in x. p will have as many elements as the inputs, u_lim and l_lim, have rows. \(Pr(X ≥ l\_lim \text{ and } X ≤ u\_lim|corr, nonc)\).
  • 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 corr not positive semi-definite.
    missing corr not properly defined.

Examples

Uncorrelated variables

// Lower limits of integration for K dimensional multivariate distribution
a = {-1e4 -1e4};

// Upper limits of integration for K dimensional multivariate distribution
b = {0 0};

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

// Define non-centrality vector
nonc  = {0, 0};

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

/*
** Calculate cumulative probability of
** both variables being from -1e4 to  0
*/
{ p, err, retcode } = cdfMvn2e(ctl, a, b, corr, nonc);

After the above code, both p equal to 0.25.

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

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

/*
** Limits of integration
** -5 ≤ x1 ≤ -1 and -8 ≤ x2 ≤ -1.1
** -10 ≤ x1 ≤ 0 and -10 ≤ x2 ≤ 0.1
** 0 ≤ x1 ≤ 1 and 0 ≤ x2 ≤ 1.1
*/
a = {  -5  -8,
      -20 -10,
        0   0 };

b = {  -1 -1.1,
        0  0.1,
        1  1.1 };

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

// Define non-centrality vector
nonc  = {0, 0};

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

/*
** Calculate cumulative probability of
** each pair of limits
*/
{ p, err, retcode }  = cdfMvn2e(ctl, a, b, corr, nonc);

After the above code, p should equal:

0.04074118
0.31981965
0.13700266

which means that:

\[\begin{split}P(-5 \leq x_1 \leq -1 \text{ and } -8 \leq x_2 \leq -1.1) = 0.0407\\ P(-20 \leq x_1 \leq 0 \text{ and } -10 \leq x_2 \leq 0.1) = 0.3198\\ P(0 \leq x_1 \leq 1 \text{ and } 0 \leq x_2 \leq 1.1) = 0.1370\end{split}\]

Compute the non central multivariate normal cdf

/*
** Limits of integration
** -5 ≤ x1 ≤ -1 and -8 ≤ x2 ≤ -1.1
** -10 ≤ x1 ≤ 0 and -10 ≤ x2 ≤ 0.1
** 0 ≤ x1 ≤ 1 and 0 ≤ x2 ≤ 1.1
*/
a = { -5  -8,
     -20 -10,
       0   0 };

b = {  -1 -1.1,
        0  0.1,
        1  1.1 };

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

// Define non-centrality vector, Kx1
nonc  = {   1,
         -2.5 };

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

/*
** Calculate cumulative probability of
** each pair of upper limits
*/
{ p, err, retcode } = cdfMvn2e(ctl, a, b, corr, nonc);

After the above code, p should equal:

0.02246034
0.15854761
0.00094761

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

\[\begin{split}P(-5 \leq x_1 \leq -1 \text{ and } -8 \leq x_2 \leq -1.1) = 0.0225\\ P(-20 \leq x_1 \leq 0 \text{ and } -10 \leq x_2 \leq 0.1) = 0.1585\\ P(0 \leq x_1 \leq 1 \text{ and } 0 \leq x_2 \leq 1.1) = 0.0009\end{split}\]

Remarks

  • cdfMvn2e() evaluates the following non-central MVN integral, where \(1\leqslant i \leqslant N\) 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 cdfMvne(), cdfMvnce(), cdfMvt2e()