cdfMvt2e#

Purpose#

Computes multivariate Student’s t cumulative distribution function with error management over \([a, b]\).

Format#

{ y, err, retcode } = cdfMvt2e(ctl, l_lim, u_lim, corr, nonc, df)#
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, relative error tolerance.

  • l_lim (NxK matrix) – lower limits. K is the dimension of multivariate Student’s t distribution. N is the number of MVT cdf integrals.

  • u_lim (NxK matrix) – upper limits.

  • corr (KxK matrix) – correlation matrix.

  • nonc (Kx1 vector) – noncentralities.

  • df (scalar) – degrees of freedom.

Returns:
  • p (Nx1 vector) – Each element in p is the cumulative distribution function of the multivariate Student’s t distribution for the corresponding columns in l_lim and u_lim. p will have as many elements as the input, l_lim and u_lim, have rows.

  • 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
l_lim = { -1e4 -1e4 };

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

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

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

// Define degree of freedom
df  = 3;

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

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

After the above code, both p equal to 0.25.

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

Compute the multivariate student’s t cdf at 3 separate pairs of upper limits#

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

u_lim = { -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 degree of freedom
df  = 3;

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

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

After the above code, p should equal:

0.06226091
0.31743546
0.12010880

which means that:

\[\begin{split}P(-5 \leq x_1 \leq -1 \text{ and } -8 \leq x_2 \leq -1.1) = 0.0623\\ P(-20 \leq x_1 \leq +0 \text{ and } -10 \leq x_2 \leq +0.1) = 0.3174\\ P(0 \leq x_1 \leq 1 \text{ and } 0 \leq x_2 \leq 1.1) = 0.1201\end{split}\]

Compute the non central multivariate student’s t cdf#

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

 u_lim = { -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 degree of freedom
 df  = 3;

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

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

After the above code, p should equal:

0.02810292
0.15190018
0.00092484

which means with non-central vector, the multivariate student’s t cdf are:

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

Source#

cdfm.src

  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 cdfMvte(), cdfMvtce(), cdfMvn2e()