cdfMvtce#

Purpose#

Computes complement (upper tail) of multivariate Student’s t cumulative distribution function with error management.

Format#

{ y, err, retcode } = cdfMvtce(ctl, x, 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.
x (NxK matrix) – Lower limits at which to evaluate the complement of the multivariate Student’s t cumulative distribution function. If x has more than one row, each row will be treated as a separate set of upper limits. K is the dimension of the multivariate Student’s t distribution. N is the number of MVT cdf integrals.
corr (KxK matrix) – correlation matrix.
nonc (Kx1 vector) – noncentralities.
df (scalar) – degrees of freedom.

Returns:

p (Nx1 vector) – Each element in p is the complement of the cumulative distribution function of the multivariate Student’s t distribution for the corresponding elements 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 Student's t distribution
x = { 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 ≥ 0
*/
{ p, err, retcode } = cdfMvtce(ctl, x, corr, nonc, df);

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

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

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

Compute the upper tail of multivariate student’s t 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 vector
nonc  = { 0, 0 };

// Define degree of freedom
df  = 3;

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

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

After the above code, p should equal:

69617932
28156926
06752203

which means that:

\[\begin{split}P(x_1 \geq -1 \text{ and } x_2 \geq -1.1) = 0.6962\\ P(x_1 \geq +0 \text{ and } x_2 \geq +0.1) = 0.2816\\ P(x_1 \geq 1 \text{ and } x_2 \geq 1.1) = 0.0675\end{split}\]

Compute the upper tail of non central multivariate student’s t 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
  nonc  = {  1, -2.5 };

  // Define degree of freedom
  df  = 3;

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

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

After the above code, p should equal:

08623943
00468427
00049538

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

\[\begin{split}P(x_1 \geq -1 \text{ and } x_2 \geq -1.1) = 0.0862\\ P(x_1 \geq +0 \text{ and } x_2 \geq +0.1) = 0.0047\\ P(x_1 \geq 1 \text{ and } x_2 \geq 1.1) = 0.0005\end{split}\]

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, relative error tolerance.