cdfMvn ============================================== Purpose ---------------- Computes multivariate Normal cumulative distribution function. Format ---------------- .. function:: p = cdfMvn(x, corr) :param x: Values at which to evaluate the multivariate normal cumulative distribution function. If *x* has more than one column, each column will be treated as a separate set of upper limits. :type x: Kx1 vector or KxN matrix :param corr: correlation matrix. :type corr: KxK matrix :return p: 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. :rtype p: Nx1 vector Examples ---------------- Uncorrelated variables ++++++++++++++++++++++ :: // Upper limits of integration x = { 0, 0 }; /* ** Identity matrix, indicates ** zero correlation between variables */ corr = { 1 0, 0 1 }; /* ** Calculate cumulative probability of ** both variables being ≤ 0 */ p = cdfmvn(x, corr); /* ** Calculate joint probablity 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. Example 2 ++++++++++++++ :: // Upper limits of integration x = { -0.5, 1 }; // Correlation matrix corr = { 1 0.26, 0.26 1 }; /* ** Calculate cumulative probability of ** the first variable being ≤ -0.5 ** and the second variable being ≤ 1 */ p = cdfmvn(x, corr); After the above code, *p* should equal: 0.28025. It means : .. math:: \Phi = P(-\infty < X_1 \leq -0.5, - \infty < X_2 \leq 1) \approx 0.28025 when the correlation between two variables is 0.26. Compute the cdf at 3 separate pairs of points +++++++++++++++++++++++++++++++++++++++++++++ :: /* ** Upper limits of integration ** x1 ≤ -1 and x2 ≤ -1.1 ** x1 ≤ 0 and x2 ≤ 0.1 ** x1 ≤ 1 and x2 ≤ 1.1 */ x = { -1 0 1, -1.1 0.1 1.1 }; // Correlation matrix corr = { 1 0.31, 0.31 1 }; /* ** Calculate cumulative probability of ** each pair of upper limits */ p = cdfmvn(x, corr); After the above code, p should equal: :: 0.040741382 0.31981965 0.74642007 which means that: .. math:: 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 Remarks ------------ - :func:`cdfMvn` evaluates the *MVN* integral with i-th row of :math:`x` (upper limits), where :math:`1\leqslant i \leqslant N` - The correlation matrix :math:`R` is defined by :math:`\Sigma = DRD`, where :math:`D` denotes the diagonal matrix which has the square roots of the diagonal entries for covariance matrix :math:`\Sigma` on its diagonal. - :func:`cdfMvne` is more accurate and faster. Note that :func:`cdfMvne` takes a row vector of upper limits whereas :func:`cdfMvn` takes a column vector of limits. .. seealso:: Functions :func:`cdfBvn`, :func:`cdfN`, :func:`lncdfmvn`