# NAG FL Interfaceg01hcf (prob_​bivariate_​students_​t)

## ▸▿ Contents

Settings help

FL Name Style:

FL Specification Language:

## 1Purpose

g01hcf returns probabilities for the bivariate Student's $t$-distribution.

## 2Specification

Fortran Interface
 Function g01hcf ( tail, a, b, df, rho,
 Real (Kind=nag_wp) :: g01hcf Integer, Intent (In) :: df Integer, Intent (Inout) :: ifail Real (Kind=nag_wp), Intent (In) :: a(2), b(2), rho Character (1), Intent (In) :: tail
#include <nag.h>
 double g01hcf_ (const char *tail, const double a[], const double b[], const Integer *df, const double *rho, Integer *ifail, const Charlen length_tail)
The routine may be called by the names g01hcf or nagf_stat_prob_bivariate_students_t.

## 3Description

Let the vector random variable $X={\left({X}_{1},{X}_{2}\right)}^{\mathrm{T}}$ follow a bivariate Student's $t$-distribution with degrees of freedom $\nu$ and correlation $\rho$, then the probability density function is given by
 $f(X:ν,ρ) = 1 2π 1-ρ2 (1+ X12 + X22 - 2 ρ X1 X2 ν (1-ρ2) ) -ν/2-1 .$
The lower tail probability is defined by:
 $P( X1 ≤ b1 , X2 ≤ b2 :ν,ρ) = ∫ -∞ b1 ∫ -∞ b2 f(X:ν,ρ) dX2 dX1 .$
The upper tail probability is defined by:
 $P( X1 ≥ a1 , X2 ≥ a2 :ν,ρ) = ∫ a1 ∞ ∫ a2 ∞ f(X:ν,ρ) dX2 dX1 .$
The central probability is defined by:
 $P( a1 ≤ X1 ≤ b1 , a2 ≤ X2 ≤ b2 :ν,ρ) = ∫ a1 b1 ∫ a2 b2 f(X:ν,ρ) dX2 dX1 .$
Calculations use the Dunnett and Sobel (1954) method, as described by Genz (2004).
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 (2004) Numerical computation of rectangular bivariate and trivariate Normal and $t$ probabilities Statistics and Computing 14 151–160

## 5Arguments

1: $\mathbf{tail}$Character(1) Input
On entry: indicates which probability is to be returned.
${\mathbf{tail}}=\text{'L'}$
The lower tail probability is returned.
${\mathbf{tail}}=\text{'U'}$
The upper tail probability is returned.
${\mathbf{tail}}=\text{'C'}$
The central probability is returned.
Constraint: ${\mathbf{tail}}=\text{'L'}$, $\text{'U'}$ or $\text{'C'}$.
2: $\mathbf{a}\left(2\right)$Real (Kind=nag_wp) array Input
On entry: if ${\mathbf{tail}}=\text{'C'}$ or $\text{'U'}$, the lower bounds ${a}_{1}$ and ${a}_{2}$.
If ${\mathbf{tail}}=\text{'L'}$, a is not referenced.
3: $\mathbf{b}\left(2\right)$Real (Kind=nag_wp) array Input
On entry: if ${\mathbf{tail}}=\text{'C'}$ or $\text{'L'}$, the upper bounds ${b}_{1}$ and ${b}_{2}$.
If ${\mathbf{tail}}=\text{'U'}$, b is not referenced.
Constraint: if ${\mathbf{tail}}=\text{'C'}$, ${a}_{i}<{b}_{i}$, for $\mathit{i}=1,2$.
4: $\mathbf{df}$Integer Input
On entry: $\nu$, the degrees of freedom of the bivariate Student's $t$-distribution.
Constraint: ${\mathbf{df}}\ge 1$.
5: $\mathbf{rho}$Real (Kind=nag_wp) Input
On entry: $\rho$, the correlation of the bivariate Student's $t$-distribution.
Constraint: $-1.0\le {\mathbf{rho}}\le 1.0$.
6: $\mathbf{ifail}$Integer Input/Output
On entry: ifail must be set to $0$, $-1$ or $1$ to set behaviour on detection of an error; these values have no effect when no error is detected.
A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $-1$ means that an error message is printed while a value of $1$ means that it is not.
If halting is not appropriate, the value $-1$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $0$ is recommended. When the value $-\mathbf{1}$ or $\mathbf{1}$ is used it is essential to test the value of ifail on exit.
On exit: ${\mathbf{ifail}}={\mathbf{0}}$ unless the routine detects an error or a warning has been flagged (see Section 6).

## 6Error Indicators and Warnings

If on entry ${\mathbf{ifail}}=0$ or $-1$, explanatory error messages are output on the current error message unit (as defined by x04aaf).
Errors or warnings detected by the routine:
If on exit, ${\mathbf{ifail}}\ne {\mathbf{0}}$, then g01hcf returns zero.
${\mathbf{ifail}}=1$
On entry, ${\mathbf{tail}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{tail}}=\text{'L'}$, $\text{'U'}$ or $\text{'C'}$.
${\mathbf{ifail}}=3$
On entry, ${\mathbf{b}}\left(i\right)\le {\mathbf{a}}\left(i\right)$ for central probability, for some $i=1,2$.
${\mathbf{ifail}}=4$
On entry, ${\mathbf{df}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{df}}\ge 1$.
${\mathbf{ifail}}=5$
On entry, ${\mathbf{rho}}=⟨\mathit{\text{value}}⟩$.
Constraint: $-1.0\le {\mathbf{rho}}\le 1.0$.
${\mathbf{ifail}}=-99$
See Section 7 in the Introduction to the NAG Library FL Interface for further information.
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library FL Interface for further information.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

## 7Accuracy

Accuracy of the algorithm implemented here is discussed in comparison with algorithms based on a generalized Placket formula by Genz (2004), who recommends the Dunnet and Sobel method. This implementation should give a maximum absolute error of the order of ${10}^{-16}$.

## 8Parallelism and Performance

g01hcf is not threaded in any implementation.

None.

## 10Example

This example calculates the bivariate Student's $t$ probability given the choice of tail and degrees of freedom, correlation and bounds.

### 10.1Program Text

Program Text (g01hcfe.f90)

### 10.2Program Data

Program Data (g01hcfe.d)

### 10.3Program Results

Program Results (g01hcfe.r)