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_inv_cdf_students_t (g01fb)

## Purpose

nag_stat_inv_cdf_students_t (g01fb) returns the deviate associated with the given tail probability of Student's $t$-distribution with real degrees of freedom.

## Syntax

[result, ifail] = g01fb(p, df, 'tail', tail)
[result, ifail] = nag_stat_inv_cdf_students_t(p, 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 deviate, ${t}_{p}$ associated with the lower tail probability, $p$, of the Student's $t$-distribution with $\nu$ degrees of freedom is defined as the solution to
 $PT
For $\nu =1\text{​ or ​}2$ the integral equation is easily solved for ${t}_{p}$.
For other values of $\nu <3$ a transformation to the beta distribution is used and the result obtained from nag_stat_inv_cdf_beta (g01fe).
For $\nu \ge 3$ an inverse asymptotic expansion of Cornish–Fisher type is used. The algorithm is described by Hill (1970).

## References

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{p}$ – double scalar
$p$, the probability from the required Student's $t$-distribution as defined by tail.
Constraint: $0.0<{\mathbf{p}}<1.0$.
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 supplied probability represents.
${\mathbf{tail}}=\text{'U'}$
The upper tail probability, i.e., $P\left(T\ge {t}_{p}:\nu \right)$.
${\mathbf{tail}}=\text{'L'}$
The lower tail probability, i.e., $P\left(T\le {t}_{p}:\nu \right)$.
${\mathbf{tail}}=\text{'S'}$
The two tail (significance level) probability, i.e., $P\left(T\ge \left|{t}_{p}\right|:\nu \right)+P\left(T\le -\left|{t}_{p}\right|:\nu \right)$.
${\mathbf{tail}}=\text{'C'}$
The two tail (confidence interval) probability, i.e., $P\left(T\le \left|{t}_{p}\right|:\nu \right)-P\left(T\le -\left|{t}_{p}\right|:\nu \right)$.
Constraint: ${\mathbf{tail}}=\text{'U'}$, $\text{'L'}$, $\text{'S'}$ or $\text{'C'}$.

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

Note: nag_stat_inv_cdf_students_t (g01fb) may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the function:
If ${\mathbf{ifail}}={\mathbf{1}}$, ${\mathbf{2}}$ or ${\mathbf{3}}$ on exit, then nag_stat_inv_cdf_students_t (g01fb) returns zero.

Cases prefixed with W are classified as warnings and do not generate an error of type NAG:error_n. See nag_issue_warnings.

${\mathbf{ifail}}=1$
 On entry, ${\mathbf{tail}}\ne \text{'U'}$, $\text{'S'}$, $\text{'C'}$ or $\text{'L'}$.
${\mathbf{ifail}}=2$
 On entry, ${\mathbf{p}}\le 0.0$, or ${\mathbf{p}}\ge 1.0$.
${\mathbf{ifail}}=3$
 On entry, ${\mathbf{df}}<1.0$.
W  ${\mathbf{ifail}}=5$
Convergence in the calculation of the inverse beta value was not achieved. However, the result should be a reasonable approximation to the correct value.
${\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 results should be accurate to five significant digits, for most argument values. The error behaviour for various argument values is discussed in Hill (1970).

The value ${t}_{p}$ may be calculated by using the transformation described in Description and using nag_stat_inv_cdf_beta (g01fe). This function allows you to set the required accuracy.

## Example

This example reads the probability, the tail that probability represents and the degrees of freedom for a number of Student's $t$-distributions and computes the corresponding deviates.
```function g01fb_example

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

p    = [ 0.01;          0.01;        0.99];
df   = [20;             7.5;        45.00];
tail = {'Significance'; 'Lower'; 'Confidence' };

fprintf('      p      df    tail      x\n');
for j = 1:numel(p);

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

fprintf('%9.3f%8.3f%4s%12.3f\n', p(j), df(j), tail{j}(1), x);
end

```
```g01fb example results

p      df    tail      x
0.010  20.000   S       2.845
0.010   7.500   L      -2.943
0.990  45.000   C       2.690
```