g01 Chapter Contents
g01 Chapter Introduction
NAG Library Manual

# NAG Library Function Documentnag_multi_students_t (g01hdc)

## 1  Purpose

nag_multi_students_t (g01hdc) returns a probability associated with a multivariate Student's $t$-distribution.

## 2  Specification

 #include #include
 double nag_multi_students_t (Integer n, const Nag_TailProbability tail[], const double a[], const double b[], double nu, const double delta[], Nag_Boolean iscov, double rc[], Integer pdrc, double epsabs, double epsrel, Integer numsub, Integer nsampl, Integer fmax, double *errest, NagError *fail)

## 3  Description

A random vector $x\in {ℝ}^{n}$ that follows a Student's $t$-distribution with $\nu$ degrees of freedom and covariance matrix $\Sigma$ has density:
 $Γ ν+n / 2 Γ ν/2 νn/2 πn/2 Σ 1/2 1+ 1ν xT Σ-1x ν+n / 2 ,$
and probability $p$ given by:
 $p = Γ ν+n / 2 Γ ν/2 Σ πνn ∫ a1 b1 ∫ a2 b2 ⋯ ∫ an bn 1+ xT Σ-1x/ν - ν+n/2 dx .$
The method of calculation depends on the dimension $n$ and degrees of freedom $\nu$. The method of Dunnet and Sobel 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 Dunnet and Sobel 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$, nag_multi_students_t (g01hdc) attempts to evaluate probabilities within a requested accuracy $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\epsilon }_{a},{\epsilon }_{r}×I\right)$, for an approximate integral value $I$, absolute accuracy ${\epsilon }_{a}$ and relative accuracy ${\epsilon }_{r}$.
Dunnet 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

## 5  Arguments

1:     nIntegerInput
On entry: $n$, the number of dimensions.
Constraint: $1<{\mathbf{n}}\le 1000$.
2:     tail[n]const Nag_TailProbabilityInput
On entry: defines the calculated probability, set ${\mathbf{tail}}\left[i-1\right]$ to:
${\mathbf{tail}}\left[i-1\right]=\mathrm{Nag_LowerTail}$
If the $i$th lower limit ${a}_{i}$ is negative infinity.
${\mathbf{tail}}\left[i-1\right]=\mathrm{Nag_UpperTail}$
If the $i$th upper limit ${b}_{i}$ is infinity.
${\mathbf{tail}}\left[i-1\right]=\mathrm{Nag_Central}$
If both ${a}_{i}$ and ${b}_{i}$ are finite.
Constraint: ${\mathbf{tail}}\left[\mathit{i}-1\right]=\mathrm{Nag_LowerTail}$, $\mathrm{Nag_UpperTail}$ or $\mathrm{Nag_Central}$, for $\mathit{i}=1,2,\dots ,{\mathbf{n}}$.
3:     a[n]const doubleInput
On entry: ${a}_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,n$, the lower integral limits of the calculation.
If ${\mathbf{tail}}\left[i-1\right]=\mathrm{Nag_LowerTail}$, ${\mathbf{a}}\left[i-1\right]$ is not referenced and the $i$th lower limit of integration is $-\infty$.
4:     b[n]const doubleInput
On entry: ${b}_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,n$, the upper integral limits of the calculation.
If ${\mathbf{tail}}\left[i-1\right]=\mathrm{Nag_UpperTail}$, ${\mathbf{b}}\left[i-1\right]$ is not referenced and the $i$th upper limit of integration is $\infty$.
Constraint: if ${\mathbf{tail}}\left[i-1\right]=\mathrm{Nag_Central}$, ${\mathbf{b}}\left[i-1\right]>{\mathbf{a}}\left[i-1\right]$.
5:     nudoubleInput
On entry: $\nu$, the degrees of freedom.
Constraint: ${\mathbf{nu}}>0.0$.
6:     delta[n]const doubleInput
On entry: ${\mathbf{delta}}\left[\mathit{i}-1\right]$ the noncentrality parameter for the $\mathit{i}$th dimension, for $\mathit{i}=1,2,\dots ,{\mathbf{n}}$; set ${\mathbf{delta}}\left[i-1\right]=0$ for the central probability.
7:     iscovNag_BooleanInput
On entry: set ${\mathbf{iscov}}=\mathrm{Nag_TRUE}$ if the covariance matrix is supplied and ${\mathbf{iscov}}=\mathrm{Nag_FALSE}$ if the correlation matrix is supplied.
8:     rc[${\mathbf{n}}×{\mathbf{pdrc}}$]doubleInput/Output
Note: the $\left(i,j\right)$th element of the matrix is stored in ${\mathbf{rc}}\left[\left(i-1\right)×{\mathbf{pdrc}}+j-1\right]$.
On entry: the lower triangle of either the covariance matrix (if ${\mathbf{iscov}}=\mathrm{Nag_TRUE}$) or the correlation matrix (if ${\mathbf{iscov}}=\mathrm{Nag_FALSE}$). In either case the array elements corresponding to the upper triangle of the matrix need not be set.
On exit: the strict upper triangle of rc contains the correlation matrix used in the calculations.
9:     pdrcIntegerInput
On entry: the stride separating matrix column elements in the array rc.
Constraint: ${\mathbf{pdrc}}\ge {\mathbf{n}}$.
10:   epsabsdoubleInput
On entry: ${\epsilon }_{a}$, the absolute accuracy requested in the approximation. If epsabs is negative, the absolute value is used.
Suggested value: $0.0$.
11:   epsreldoubleInput
On entry: ${\epsilon }_{r}$, the relative accuracy requested in the approximation. If epsrel is negative, the absolute value is used.
Suggested value: $0.001$.
12:   numsubIntegerInput
On entry: if quadrature is used, the number of sub-intervals used by the quadrature algorithm; otherwise numsub is not referenced.
Suggested value: $350$.
Constraint: if referenced, ${\mathbf{numsub}}>0$.
13:   nsamplIntegerInput
On entry: if quadrature is used, nsampl is not referenced; otherwise nsampl is the number of samples used to estimate the error in the approximation.
Suggested value: $8$
Constraint: if referenced, ${\mathbf{nsampl}}>0$.
14:   fmaxIntegerInput
On entry: if a number theoretic approach is used, the maximum number of evaluations for each integrand function.
Suggested value: $1000×{\mathbf{n}}$
Constraint: if referenced, ${\mathbf{fmax}}\ge 1$.
15:   errestdouble *Output
On exit: an estimate of the error in the calculated probability.
16:   failNagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

## 6  Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
NE_ARRAY_SIZE
On entry, ${\mathbf{pdrc}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{pdrc}}\ge {\mathbf{n}}$.
On entry, argument $⟨\mathit{\text{value}}⟩$ had an illegal value.
NE_INT
On entry, ${\mathbf{fmax}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{fmax}}\ge 1$.
On entry, ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: $1<{\mathbf{n}}\le 1000$.
On entry, ${\mathbf{nsampl}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{nsampl}}\ge 1$.
On entry, ${\mathbf{numsub}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{numsub}}\ge 1$.
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
NE_INVALID_ARRAY
On entry, the information supplied in rc is invalid.
NE_REAL
On entry, ${\mathbf{nu}}=⟨\mathit{\text{value}}⟩$.
Constraint: degrees of freedom ${\mathbf{nu}}>0.0$.
NE_REAL_2
On entry, $k=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{b}}\left[k-1\right]>{\mathbf{a}}\left[k-1\right]$ for a central probability.

## 7  Accuracy

An estimate of the error in the calculation is given by the value of errest on exit.

## 8  Parallelism and Performance

nag_multi_students_t (g01hdc) is not threaded by NAG in any implementation.
nag_multi_students_t (g01hdc) makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.

None.

## 10  Example

This example prints two probabilities from the Student's $t$-distribution.

### 10.1  Program Text

Program Text (g01hdce.c)

### 10.2  Program Data

Program Data (g01hdce.d)

### 10.3  Program Results

Program Results (g01hdce.r)