cdfMvt2e ============================================== Purpose ---------------- Computes multivariate Student's t cumulative distribution function with error management over :math:[a, b]. Format ---------------- .. function:: { y, err, retcode } = cdfMvt2e(ctl, l_lim, u_lim, corr, nonc, df ) :param ctl: instance of a :class:cdfmControl structure with members .. csv-table:: :widths: auto "ctl.maxEvaluations", "scalar, maximum number of evaluations." "ctl.absErrorTolerance", "scalar, absolute error tolerance." "ctl.relErrorTolerance", "scalar, relative error tolerance." :type ctl: struct :param l_lim: lower limits. *K* is the dimension of multivariate Student's t distribution. *N* is the number of MVT cdf integrals. :type l_lim: NxK matrix :param u_lim: upper limits. :type u_lim: NxK matrix :param corr: correlation matrix. :type corr: KxK matrix :param nonc: noncentralities. :type nonc: Kx1 vector :param df: degrees of freedom. :type df: scalar :return p: 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. :rtype p: Nx1 vector :return err: estimates of absolute error. :rtype err: Nx1 vector :return retcode: return codes. .. csv-table:: :widths: auto "0", "normal completion with :math:err < ctl.absErrorTolerance." "1", ":math:err > ctl.absErrorTolerance and ctl.maxEvaluations exceeded; increase ctl.maxEvaluations to decrease error." "2", ":math:K > 100 or :math:K < 1." "3", "*R* not positive semi-definite." "missing", "*R* not properly defined." :rtype retcode: Nx1 vector 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. .. math:: 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: .. math:: 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 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: .. math:: 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 Source ------------ cdfm.src #. 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. .. seealso:: Functions :func:cdfMvte, :func:cdfMvtce, :func:cdfMvn2e