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_students_t (g01eb)

## Purpose

nag_stat_prob_students_t (g01eb) returns the lower tail, upper tail or two tail probability for the Student's $t$-distribution with real degrees of freedom.

## Syntax

[result, ifail] = g01eb(t, df, 'tail', tail)
[result, ifail] = nag_stat_prob_students_t(t, df, 'tail', tail)
Note: the interface to this routine has changed since earlier releases of the toolbox:
 At Mark 23: tail was made optional (default 'L')

## Description

The lower tail probability for the Student's $t$-distribution with $\nu$ degrees of freedom, $P\left(T\le t:\nu \right)$ is defined by:
 $P T≤t:ν = Γ ν+1 / 2 πν Γν/2 ∫ -∞ t 1+ T2ν -ν+1 / 2 dT , ν≥1 .$
Computationally, there are two situations:
(i) when $\nu <20$, a transformation of the beta distribution, ${P}_{\beta }\left(B\le \beta :a,b\right)$ is used
 $P T≤t:ν = 12 Pβ B≤ ν ν+t2 : ν/2, 12 when ​ t<0.0$
or
 $P T≤t:ν = 12 + 12 Pβ B≥ ν ν+t2 : ν/2, 12 when ​ t>0.0 ;$
(ii) when $\nu \ge 20$, an asymptotic normalizing expansion of the Cornish–Fisher type is used to evaluate the probability, see Hill (1970).

## References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Hastings N A J and Peacock J B (1975) Statistical Distributions Butterworth
Hill G W (1970) Student's $t$-distribution Comm. ACM 13(10) 617–619

## Parameters

### Compulsory Input Parameters

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

### Optional Input Parameters

1:     $\mathrm{tail}$ – string (length ≥ 1)
Default: $\text{'L'}$
Indicates which tail the returned probability should represent.
${\mathbf{tail}}=\text{'U'}$
The upper tail probability is returned, i.e., $P\left(T\ge t:\nu \right)$.
${\mathbf{tail}}=\text{'S'}$
The two tail (significance level) probability is returned,
i.e., $P\left(T\ge \left|t\right|:\nu \right)+P\left(T\le -\left|t\right|:\nu \right)$.
${\mathbf{tail}}=\text{'C'}$
The two tail (confidence interval) probability is returned,
i.e., $P\left(T\le \left|t\right|:\nu \right)-P\left(T\le -\left|t\right|:\nu \right)$.
${\mathbf{tail}}=\text{'L'}$
The lower tail probability is returned, i.e., $P\left(T\le t:\nu \right)$.
Constraint: ${\mathbf{tail}}=\text{'U'}$, $\text{'S'}$, $\text{'C'}$ or $\text{'L'}$.

### 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 ${\mathbf{ifail}}\ne {\mathbf{0}}$, then nag_stat_prob_students_t (g01eb) returns $0.0$.
${\mathbf{ifail}}=1$
 On entry, ${\mathbf{tail}}\ne \text{'U'}$, $\text{'S'}$, $\text{'C'}$ or $\text{'L'}$.
${\mathbf{ifail}}=2$
 On entry, ${\mathbf{df}}<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

The computed probability should be accurate to five significant places for reasonable probabilities but there will be some loss of accuracy for very low probabilities (less than ${10}^{-10}$), see Hastings and Peacock (1975).

The probabilities could also be obtained by using the appropriate transformation to a beta distribution (see Abramowitz and Stegun (1972)) and using nag_stat_prob_beta (g01ee). This function allows you to set the required accuracy.

## Example

This example reads values from, and degrees of freedom for Student's $t$-distributions along with the required tail. The probabilities are calculated and printed until the end of data is reached.
```function g01eb_example

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

% Probability for Students' t distribution
t    = 0.85;
df   = 20;
tail = {'Lower'; 'Significance'; 'Confidence'; 'Upper'};

fprintf('  Tail    t      df    probability\n');
for j = 1:size(tail,1);

[p, ifail] = g01eb( ...
t, df, 'tail', tail{j});

fprintf('%4s%8.3f%8.1f%12.4f\n', tail{j}(1), t, df, p);
end

```
```g01eb example results

Tail    t      df    probability
L   0.850    20.0      0.7973
S   0.850    20.0      0.4054
C   0.850    20.0      0.5946
U   0.850    20.0      0.2027
```