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

C Header Interface

#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.

3 Description

Let the vector random variable

X = {(X_{1}, X_{2})}^{T}

follow a bivariate Student's

t

-distribution with degrees of freedom

ν

and correlation

ρ

, then the probability density function is given by

f (X : ν, ρ) = \frac{1}{2 π \sqrt{1 - ρ^{2}}} {(1 + \frac{X_{1}^{2} + X_{2}^{2} - 2 ρ X_{1} X_{2}}{ν (1 - ρ^{2})})}^{- ν / 2 - 1} .

The lower tail probability is defined by:

P (X_{1} \leq b_{1}, X_{2} \leq b_{2} : ν, ρ) = \int_{- \infty}^{b_{1}} \int_{- \infty}^{b_{2}} f (X : ν, ρ) d X_{2} d X_{1} .

The upper tail probability is defined by:

P (X_{1} \geq a_{1}, X_{2} \geq a_{2} : ν, ρ) = \int_{a_{1}}^{\infty} \int_{a_{2}}^{\infty} f (X : ν, ρ) d X_{2} d X_{1} .

The central probability is defined by:

P (a_{1} \leq X_{1} \leq b_{1}, a_{2} \leq X_{2} \leq b_{2} : ν, ρ) = \int_{a_{1}}^{b_{1}} \int_{a_{2}}^{b_{2}} f (X : ν, ρ) d X_{2} d X_{1} .

Calculations use the Dunnett and Sobel (1954) method, as described by Genz (2004).

4 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 (2004) Numerical computation of rectangular bivariate and trivariate Normal and

t

probabilities Statistics and Computing 14 151–160

5 Arguments

1: $tail$ – Character(1) Input

On entry: indicates which probability is to be returned.

$tail ='L'$: The lower tail probability is returned.
$tail ='U'$: The upper tail probability is returned.
$tail ='C'$: The central probability is returned.

Constraint:

tail ='L'

'U'

'C'

2: $a (2)$ – Real (Kind=nag_wp) array Input

On entry: if

tail ='C'

'U'

, the lower bounds

a_{1}

and

a_{2}

tail ='L'

, a is not referenced.

3: $b (2)$ – Real (Kind=nag_wp) array Input

On entry: if

tail ='C'

'L'

, the upper bounds

b_{1}

and

b_{2}

tail ='U'

, b is not referenced.

Constraint: if

tail ='C'

a_{i} < b_{i}

, for

i = 1, 2

4: $df$ – Integer Input

On entry:

ν

, the degrees of freedom of the bivariate Student's

t

-distribution.

Constraint:

df \geq 1

5: $rho$ – Real (Kind=nag_wp) Input

On entry:

ρ

, the correlation of the bivariate Student's

t

-distribution.

Constraint:

- 1.0 \leq rho \leq 1.0

6: $ifail$ – Integer Input/Output

On entry: ifail must be set to

0

−1

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

1

is recommended. If message printing is undesirable, then the value

1

is recommended. Otherwise, the value

0

is recommended. When the value $- 1$ or $1$ is used it is essential to test the value of ifail on exit.

On exit:

ifail = 0

unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry

ifail = 0

−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,

ifail \neq 0

, then g01hcf returns zero.

$ifail = 1$: On entry, $tail = ⟨ value ⟩$ .
Constraint: $tail ='L'$ , $'U'$ or $'C'$ .

$ifail = 3$: On entry, $b (i) \leq a (i)$ for central probability, for some $i = 1, 2$ .

$ifail = 4$: On entry, $df = ⟨ value ⟩$ .
Constraint: $df \geq 1$ .

$ifail = 5$: On entry, $rho = ⟨ value ⟩$ .
Constraint: $- 1.0 \leq rho \leq 1.0$ .

$ifail = - 99$: An unexpected error has been triggered by this routine. Please contact NAG.
See Section 7 in the Introduction to the NAG Library FL Interface for further information.

$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.

$ifail = - 999$: Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

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}

8 Parallelism and Performance

Background information to multithreading can be found in the Multithreading documentation.

g01hcf is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example calculates the bivariate Student's

t

probability given the choice of tail and degrees of freedom, correlation and bounds.

g01hc: FL CL CPP AD PY MB

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

▸▿ Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results

NAG FL Interface
g01hcf (prob_bivariate_students_t)