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$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:
Mark 23: tail now optional (default 'l')
.

## Description

The deviate, tp${t}_{p}$ associated with the lower tail probability, p$p$, of the Student's t$t$-distribution with ν$\nu$ degrees of freedom is defined as the solution to
 tp P(T < tp : ν) = p = (Γ((ν + 1) / 2))/(sqrt(νπ)Γ(ν / 2)) ∫ (1 + (T2)/ν) − (ν + 1) / 2dT,  ν ≥ 1; ​ − ∞ < tp < ∞. − ∞
$P(T
For ν = 1​ or ​2$\nu =1\text{​ or ​}2$ the integral equation is easily solved for tp${t}_{p}$.
For other values of ν < 3$\nu <3$ a transformation to the beta distribution is used and the result obtained from nag_stat_inv_cdf_beta (g01fe).
For ν3$\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$t$-distribution Comm. ACM 13(10) 617–619

## Parameters

### Compulsory Input Parameters

1:     p – double scalar
p$p$, the probability from the required Student's t$t$-distribution as defined by tail.
Constraint: 0.0 < p < 1.0$0.0<{\mathbf{p}}<1.0$.
2:     df – double scalar
ν$\nu$, the degrees of freedom of the Student's t$t$-distribution.
Constraint: df1.0${\mathbf{df}}\ge 1.0$.

### Optional Input Parameters

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

None.

### Output Parameters

1:     result – double scalar
The result of the function.
2:     ifail – int64int32nag_int scalar
${\mathrm{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}}$, 2${\mathbf{2}}$ or 3${\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.

ifail = 1${\mathbf{ifail}}=1$
 On entry, tail ≠ 'U'${\mathbf{tail}}\ne \text{'U'}$, 'S'$\text{'S'}$, 'C'$\text{'C'}$ or 'L'$\text{'L'}$.
ifail = 2${\mathbf{ifail}}=2$
 On entry, p ≤ 0.0${\mathbf{p}}\le 0.0$, or p ≥ 1.0${\mathbf{p}}\ge 1.0$.
ifail = 3${\mathbf{ifail}}=3$
 On entry, df < 1.0${\mathbf{df}}<1.0$.
W ifail = 5${\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.

## Accuracy

The results should be accurate to five significant digits, for most parameter values. The error behaviour for various parameter values is discussed in Hill (1970).

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

## Example

```function nag_stat_inv_cdf_students_t_example
p = 0.01;
df = 20;
[result, ifail] = nag_stat_inv_cdf_students_t(p, df, 'tail', 's')
```
```

result =

2.8453

ifail =

0

```
```function g01fb_example
p = 0.01;
df = 20;
[result, ifail] = g01fb(p, df, 'tail', 's')
```
```

result =

2.8453

ifail =

0

```