g01 Chapter Contents
g01 Chapter Introduction
NAG Library Manual

# NAG Library Function Documentnag_deviates_students_t (g01fbc)

## 1  Purpose

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

## 2  Specification

 #include #include
 double nag_deviates_students_t (Nag_TailProbability tail, double p, double df, NagError *fail)

## 3  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_deviates_beta (g01fec).
For $\nu \ge 3$ an inverse asymptotic expansion of Cornish–Fisher type is used. The algorithm is described by Hill (1970).

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

## 5  Arguments

1:     tailNag_TailProbabilityInput
On entry: indicates which tail the supplied probability represents.
${\mathbf{tail}}=\mathrm{Nag_UpperTail}$
The upper tail probability, i.e., $P\left(T\ge {t}_{p}:\nu \right)$.
${\mathbf{tail}}=\mathrm{Nag_LowerTail}$
The lower tail probability, i.e., $P\left(T\le {t}_{p}:\nu \right)$.
${\mathbf{tail}}=\mathrm{Nag_TwoTailSignif}$
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}}=\mathrm{Nag_TwoTailConfid}$
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}}=\mathrm{Nag_UpperTail}$, $\mathrm{Nag_LowerTail}$, $\mathrm{Nag_TwoTailSignif}$ or $\mathrm{Nag_TwoTailConfid}$.
2:     pdoubleInput
On entry: $p$, the probability from the required Student's $t$-distribution as defined by tail.
Constraint: $0.0<{\mathbf{p}}<1.0$.
3:     dfdoubleInput
On entry: $\nu$, the degrees of freedom of the Student's $t$-distribution.
Constraint: ${\mathbf{df}}\ge 1.0$.
4:     failNagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

## 6  Error Indicators and Warnings

On any of the error conditions listed below except ${\mathbf{fail}}\mathbf{.}\mathbf{code}=$ NE_SOL_NOT_CONV nag_deviates_students_t (g01fbc) returns $0.0$.
NE_ALLOC_FAIL
Dynamic memory allocation failed.
On entry, argument $⟨\mathit{\text{value}}⟩$ had an illegal value.
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
NE_REAL_ARG_GE
On entry, ${\mathbf{p}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{p}}<1.0$.
NE_REAL_ARG_LE
On entry, ${\mathbf{p}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{p}}>0.0$.
NE_REAL_ARG_LT
On entry, ${\mathbf{df}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{df}}\ge 1.0$.
NE_SOL_NOT_CONV
The solution has failed to converge. However, the result should be a reasonable approximation.

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

## 8  Parallelism and Performance

Not applicable.

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

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

### 10.1  Program Text

Program Text (g01fbce.c)

### 10.2  Program Data

Program Data (g01fbce.d)

### 10.3  Program Results

Program Results (g01fbce.r)