Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_stat_prob_bivariate_students_t (g01hc)

## Purpose

nag_stat_prob_bivariate_students_t (g01hc) returns probabilities for the bivariate Student's $t$-distribution.

## Syntax

[result, ifail] = g01hc(df, rho, 'a', a, 'b', b)
[result, ifail] = nag_stat_prob_bivariate_students_t(df, rho, 'a', a, 'b', b)

## Description

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
 $fX:ν,ρ = 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 fX:ν,ρ dX2 dX1 .$
The upper tail probability is defined by:
 $P X1 ≥ a1 , X2 ≥ a2 :ν,ρ = ∫ a1 ∞ ∫ a2 ∞ fX:ν,ρ dX2 dX1 .$
The central probability is defined by:
 $P a1 ≤ X1 ≤ b1 , a2 ≤ X2 ≤ b2 :ν,ρ = ∫ a1 b1 ∫ a2 b2 fX:ν,ρ dX2 dX1 .$
Calculations use the Dunnet and Sobel (1954) method, as described by Genz (2004).

## References

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 (2004) Numerical computation of rectangular bivariate and trivariate Normal and $t$ probabilities Statistics and Computing 14 151–160

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{df}$int64int32nag_int scalar
$\nu$, the degrees of freedom of the bivariate Student's $t$-distribution.
Constraint: ${\mathbf{df}}\ge 1$.
2:     $\mathrm{rho}$ – double scalar
$\rho$, the correlation of the bivariate Student's $t$-distribution.
Constraint: $-1.0\le {\mathbf{rho}}\le 1.0$.

### Optional Input Parameters

1:     $\mathrm{a}\left(2\right)$ – double array
If upper tail or central probablilities are to be returned, a should supply the lower bounds, ${a}_{\mathit{i}}$, for $\mathit{i}=1,2$.
2:     $\mathrm{b}\left(2\right)$ – double array
If lower tail or central probablilities are to be returned, b should supply the upper bounds, ${b}_{\mathit{i}}$, for $\mathit{i}=1,2$.

### Output Parameters

1:     $\mathrm{result}$ – double scalar
The result of the function.
2:     $\mathrm{ifail}$int64int32nag_int scalar
${\mathbf{ifail}}={\mathbf{0}}$ unless the function detects an error (see Error Indicators and Warnings).

## Error Indicators and Warnings

Errors or warnings detected by the function:
If on exit, ${\mathbf{ifail}}\ne 0$, then nag_stat_prob_bivariate_students_t (g01hc) returns zero.
${\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$
Constraint: ${\mathbf{df}}\ge 1$.
${\mathbf{ifail}}=5$
Constraint: $-1.0\le {\mathbf{rho}}\le 1.0$.
${\mathbf{ifail}}=-99$
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

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

None.

## Example

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

fprintf('g01hc example results\n\n');

a     = [-Inf    -Inf;
-40       0;
-2       8];
b     = [   4       0.8;
2       4;
Inf     Inf];
tail = {'L'; 'C'; 'U'};
df    = int64([   8;     12;      2   ]);
rho   = [   0.6;   -0.2;    0.3 ];
p     = rho;

fprintf('%9s%12s%12s%12s%7s%6s%6s%4s\n', 'a(1)', 'b(1)', 'a(2)', ...
'b(2)', 'df', 'rho','tail', 'p');
for j = 1:numel(df)
if tail{j}=='L'
[p(j), ifail] = g01hc( ...
df(j), rho(j), 'b', b(j,:));
elseif tail{j}=='C'
[p(j), ifail] = g01hc( ...
df(j), rho(j), 'a', a(j,:), 'b', b(j,:));
else
[p(j), ifail] = g01hc( ...
df(j), rho(j), 'a', a(j,:));
end
fprintf('%12.4e%12.4e%12.4e%12.4e%4d%7.4f%5s%7.4f\n', a(j,1), b(j,1), ...
a(j,2), b(j,2), df(j), rho(j), tail{j}, p(j));
end

```
```g01hc example results

a(1)        b(1)        a(2)        b(2)     df   rho  tail   p
-Inf  4.0000e+00        -Inf  8.0000e-01   8 0.6000    L 0.7764
-4.0000e+01  2.0000e+00  0.0000e+00  4.0000e+00  12-0.2000    C 0.4876
-2.0000e+00         Inf  8.0000e+00         Inf   2 0.3000    U 0.0059
```