# NAG FL Interfaceg01gdf (prob_​f_​noncentral)

## 1Purpose

g01gdf returns the probability associated with the lower tail of the noncentral $F$ or variance-ratio distribution.

## 2Specification

Fortran Interface
 Function g01gdf ( f, df1, df2, tol,
 Real (Kind=nag_wp) :: g01gdf Integer, Intent (In) :: maxit Integer, Intent (Inout) :: ifail Real (Kind=nag_wp), Intent (In) :: f, df1, df2, rlamda, tol
#include <nag.h>
 double g01gdf_ (const double *f, const double *df1, const double *df2, const double *rlamda, const double *tol, const Integer *maxit, Integer *ifail)
The routine may be called by the names g01gdf or nagf_stat_prob_f_noncentral.

## 3Description

The lower tail probability of the noncentral $F$-distribution with ${\nu }_{1}$ and ${\nu }_{2}$ degrees of freedom and noncentrality parameter $\lambda$, $P\left(F\le f:{\nu }_{1},{\nu }_{2}\text{;}\lambda \right)$, is defined by
 $PF≤f:ν1,ν2;λ=∫0xpF:ν1,ν2;λdF,$
where
 $PF : ν1,ν2;λ =∑j= 0∞e-λ/2 λ/2jj! ×ν1+ 2jν1+ 2j/2 ν2ν2/2 Bν1+ 2j/2,ν2/2$
 $×uν1+2j-2/2ν2+ν1+2ju -ν1+2j+ν2/2$
and $B\left(·,·\right)$ is the beta function.
The probability is computed by means of a transformation to a noncentral beta distribution:
 $PF≤f:ν1,ν2;λ=PβX≤x:a,b;λ,$
where $x=\frac{{\nu }_{1}f}{{\nu }_{1}f+{\nu }_{2}}$ and ${P}_{\beta }\left(X\le x:a,b\text{;}\lambda \right)$ is the lower tail probability integral of the noncentral beta distribution with parameters $a$, $b$, and $\lambda$.
If ${\nu }_{2}$ is very large, greater than ${10}^{6}$, then a ${\chi }^{2}$ approximation is used.

## 4References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

## 5Arguments

1: $\mathbf{f}$Real (Kind=nag_wp) Input
On entry: $f$, the deviate from the noncentral $F$-distribution.
Constraint: ${\mathbf{f}}>0.0$.
2: $\mathbf{df1}$Real (Kind=nag_wp) Input
On entry: the degrees of freedom of the numerator variance, ${\nu }_{1}$.
Constraint: $0.0<{\mathbf{df1}}\le {10}^{6}$.
3: $\mathbf{df2}$Real (Kind=nag_wp) Input
On entry: the degrees of freedom of the denominator variance, ${\nu }_{2}$.
Constraint: ${\mathbf{df2}}>0.0$.
4: $\mathbf{rlamda}$Real (Kind=nag_wp) Input
On entry: $\lambda$, the noncentrality parameter.
Constraint: $0.0\le {\mathbf{rlamda}}\le -2.0\mathrm{log}\left(U\right)$ where $U$ is the safe range parameter as defined by x02amf.
5: $\mathbf{tol}$Real (Kind=nag_wp) Input
On entry: the relative accuracy required by you in the results. If g01gdf is entered with tol greater than or equal to $1.0$ or less than (see x02ajf), the value of is used instead.
6: $\mathbf{maxit}$Integer Input
On entry: the maximum number of iterations to be used.
Suggested value: $500$. See g01gcf and g01gef for further details.
Constraint: ${\mathbf{maxit}}\ge 1$.
7: $\mathbf{ifail}$Integer Input/Output
On entry: ifail must be set to $0$, $-1$ or $1$ to set behaviour on detection of an error; these values have no effect when no error is detected.
A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $-1$ means that an error message is printed while a value of $1$ means that it is not.
If halting is not appropriate, the value $-1$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $-1$ is recommended since useful values can be provided in some output arguments even when ${\mathbf{ifail}}\ne {\mathbf{0}}$ on exit. When the value $-\mathbf{1}$ or $\mathbf{1}$ is used it is essential to test the value of ifail on exit.
On exit: ${\mathbf{ifail}}={\mathbf{0}}$ unless the routine detects an error or a warning has been flagged (see Section 6).

## 6Error Indicators and Warnings

If on entry ${\mathbf{ifail}}=0$ or $-1$, explanatory error messages are output on the current error message unit (as defined by x04aaf).
Errors or warnings detected by the routine:
Note: in some cases g01gdf may return useful information.
If on exit ${\mathbf{ifail}}={\mathbf{1}}$ or ${\mathbf{3}}$, then g01gdf returns $0.0$.
${\mathbf{ifail}}=1$
On entry, ${\mathbf{df1}}=〈\mathit{\text{value}}〉$.
Constraint: $0.0<{\mathbf{df1}}\le {10}^{6}$.
On entry, ${\mathbf{df1}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{df1}}>0.0$.
On entry, ${\mathbf{df2}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{df2}}>0.0$.
On entry, ${\mathbf{f}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{f}}>0.0$.
On entry, ${\mathbf{maxit}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{maxit}}\ge 1$.
On entry, ${\mathbf{rlamda}}=〈\mathit{\text{value}}〉$.
Constraint: $0.0\le {\mathbf{rlamda}}\le -2.0×\mathrm{log}\left(U\right)$, where $U$ is the safe range parameter as defined by x02amf.
${\mathbf{ifail}}=2$
The solution has failed to converge in $〈\mathit{\text{value}}〉$ iterations. Consider increasing maxit or tol.
${\mathbf{ifail}}=3$
The required probability cannot be computed accurately. This may happen if the result would be very close to zero or one. Alternatively the values of df1 and f may be too large. In the latter case you could try using a normal approximation, see Abramowitz and Stegun (1972).
${\mathbf{ifail}}=4$
The required accuracy was not achieved when calculating the initial value of the central $F$ or ${\chi }^{2}$ probability. You should try a larger value of tol. If the ${\chi }^{2}$ approximation is being used then g01gdf returns zero otherwise the value returned should be an approximation to the correct value.
${\mathbf{ifail}}=-99$
See Section 7 in the Introduction to the NAG Library FL Interface for further information.
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library FL Interface for further information.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

## 7Accuracy

The relative accuracy should be as specified by tol. For further details see g01gcf and g01gef.

## 8Parallelism and Performance

g01gdf is not threaded in any implementation.

When both ${\nu }_{1}$ and ${\nu }_{2}$ are large a Normal approximation may be used and when only ${\nu }_{1}$ is large a ${\chi }^{2}$ approximation may be used. In both cases $\lambda$ is required to be of the same order as ${\nu }_{1}$. See Abramowitz and Stegun (1972) for further details.

## 10Example

This example reads values from, and degrees of freedom for, $F$-distributions, computes the lower tail probabilities and prints all these values until the end of data is reached.

### 10.1Program Text

Program Text (g01gdfe.f90)

### 10.2Program Data

Program Data (g01gdfe.d)

### 10.3Program Results

Program Results (g01gdfe.r)