cdfMvne

Purpose

Computes multivariate Normal cumulative distribution function with error management.

Format

{ y, err, retcode } = cdfMvne(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 error tolerance.
  • x (1xK vector or NxK matrix) – Upper limits at which to evaluate the lower tail 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) – 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 input, x, has columns.
  • 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

// Upper 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 vector
nonc = { 0, 0 };

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

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

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

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

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

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

/*
** Upper 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
nonc  = { 0, 0 };

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

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

After the above code, p should equal:

0.040741382
0.31981965
0.74642007

which means that:

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

Compute the non central multivariate normal cdf

/* Upper 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  = { 1, -2.5 };

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

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

After the above code, p should equal:

0.02246034
0.15854761
0.49998320

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

\[\begin{split}P(x_1 \leq -1 \text{ and } x_2 \leq -1.1) = 0.0225\\ P(x_1 \leq +0 \text{ and } x_2 \leq +0.1) = 0.1585\\ P(x_1 \leq 1 \text{ and } x_2 \leq 1.1) = 0.5000\end{split}\]

Remarks

  • cdfMvne evaluates the MVN integral, where \(1\leqslant i \leqslant N\) For the non-central MVN we have where \(z\) denotes \(K\) -dimensional multivariate normal distribution, 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(), cdfMvn2e(), cdfMvte()