naginterfaces.library.stat.prob_​multi_​students_​t

naginterfaces.library.stat.prob_multi_students_t(tail, a, b, nu, delta, iscov, rc, epsabs=0.0, epsrel=0.001, numsub=350, nsampl=8, fmax=None)

prob_multi_students_t returns a probability associated with a multivariate Student’s $t$-distribution.

For full information please refer to the NAG Library document for g01hd

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/g01/g01hdf.html

Parameters

tailstr, length 1, array-like, shape $\left(n\right)$

Defines the calculated probability, set $tail[i-1]$ to:

$tail[i-1]=\text{'L'}$

If the $i$th lower limit $a_i$ is negative infinity.

$tail[i-1]=\text{'U'}$

If the $i$th upper limit $b_i$ is infinity.

$tail[i-1]=\text{'C'}$

If both $a_i$ and $b_i$ are finite.

afloat, array-like, shape $\left(n\right)$

$a_{\text{i}}$, for $\text{i}=1,2,\dots ,n$, the lower integral limits of the calculation.

If $tail[i-1]=\text{'L'}$, $a[i-1]$ is not referenced and the $i$th lower limit of integration is $-\infty$.

bfloat, array-like, shape $\left(n\right)$

$b_{\text{i}}$, for $\text{i}=1,2,\dots ,n$, the upper integral limits of the calculation.

If $tail[i-1]=\text{'U'}$, $b[i-1]$ is not referenced and the $i$th upper limit of integration is $\infty$.

nufloat

$\nu$, the degrees of freedom.

deltafloat, array-like, shape $\left(n\right)$

$delta[\text{i}-1]$ the noncentrality parameter for the $\text{i}$th dimension, for $\text{i}=1,2,\dots ,n$; set $delta[i-1]=0$ for the central probability.

iscovint

Set $iscov=1$ if the covariance matrix is supplied and $iscov=2$ if the correlation matrix is supplied.

rcfloat, array-like, shape $(n,n)$

The lower triangle of either the covariance matrix (if $iscov=1$) or the correlation matrix (if $iscov=2$). In either case the array elements corresponding to the upper triangle of the matrix need not be set.

epsabsfloat, optional

${ϵ}_a$, the absolute accuracy requested in the approximation. If $epsabs$ is negative, the absolute value is used.

epsrelfloat, optional

${ϵ}_r$, the relative accuracy requested in the approximation. If $epsrel$ is negative, the absolute value is used.

numsubint, optional

If quadrature is used, the number of sub-intervals used by the quadrature algorithm; otherwise $numsub$ is not referenced.

nsamplint, optional

If quadrature is used, $nsampl$ is not referenced; otherwise $nsampl$ is the number of samples used to estimate the error in the approximation.

fmaxNone or int, optional

Note: if this argument is None then a default value will be used, determined as follows: $1000\times n$.

If a number theoretic approach is used, the maximum number of evaluations for each integrand function.

Returns

pfloat

The probability associated with the multivariate Student’s $t$-distribution.

rcfloat, ndarray, shape $(n,n)$

The strict upper triangle of $rc$ contains the correlation matrix used in the calculations.

errestfloat

An estimate of the error in the calculated probability.

Raises

NagValueError

(errno $1$)

On entry, $n=⟨value⟩$.

Constraint: $1<n\le 1000$.

(errno $2$)

On entry, $tail[k-1]=⟨value⟩$.

Constraint: $tail[\text{k}-1]=\text{'L'}$, $\text{'U'}$ or $\text{'C'}$.

(errno $4$)

On entry, $k=⟨value⟩$.

Constraint: $b[k-1]>a[k-1]$ for a central probability.

(errno $5$)

On entry, $nu=⟨value⟩$.

Constraint: degrees of freedom $nu>0.0$.

(errno $8$)

On entry, $iscov=⟨value⟩$.

Constraint: $iscov=1$ or $2$.

(errno $9$)

On entry, the information supplied in $rc$ is invalid.

(errno $12$)

On entry, $numsub=⟨value⟩$.

Constraint: $numsub\ge 1$.

(errno $13$)

On entry, $nsampl=⟨value⟩$.

Constraint: $nsampl\ge 1$.

(errno $14$)

On entry, $fmax=⟨value⟩$.

Constraint: $fmax\ge 1$.

Notes

A random vector $x\in R^n$ that follows a Student’s $t$-distribution with $\nu$ degrees of freedom and covariance matrix $\Sigma$ has density:

$$\frac{\Gamma \left((\nu +n)/2\right)}{\Gamma \left(\nu /2\right){\nu }^{n/2}{\pi }^{n/2}{\left|\Sigma \right|}^{1/2}{[1+\frac{1}{\nu }{x}^T{\Sigma }^{-1}x]}^{(\nu +n)/2}}\text{,}$$

and probability $p$ given by:

$$p=\frac{\Gamma \left((\nu +n)/2\right)}{\Gamma \left(\nu /2\right)\sqrt{\left|\Sigma \right|{\left(\pi \nu \right)}^n}}{\int }_{a_1}^{b_1}{\int }_{a_2}^{b_2}\cdots {\int }_{a_n}^{b_n}{(1+x^T{\Sigma }^{-1}x/\nu )}^{-(\nu +n)/2}dx\text{.}$$

The method of calculation depends on the dimension $n$ and degrees of freedom $\nu$. The method of Dunnett and Sobel (1954) is used in the bivariate case if $\nu$ is a whole number. A Plackett transform followed by quadrature method is adopted in other bivariate cases and trivariate cases. In dimensions higher than three a number theoretic approach to evaluating multidimensional integrals is adopted.

Error estimates are supplied as the published accuracy in the Dunnett and Sobel (1954) case, a Monte Carlo standard error for multidimensional integrals, and otherwise the quadrature error estimate.

A parameter $\delta$ allows for non-central probabilities. The number theoretic method is used if any $\delta$ is nonzero.

In cases other than the central bivariate with whole $\nu$, prob_multi_students_t attempts to evaluate probabilities within a requested accuracy $max({ϵ}_a,{ϵ}_r\times I)$, for an approximate integral value $I$, absolute accuracy ${ϵ}_a$ and relative accuracy ${ϵ}_r$.

References

Dunnett, C W and Sobel, M, 1954, A bivariate generalization of Student’s $t$ -distribution, with tables for certain special cases, Biometrika (41), 153–169

Genz, A and Bretz, F, 2002, Methods for the computation of multivariate $t$ -probabilities, Journal of Computational and Graphical Statistics ((11)), 950–971