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_f (g01ed)

## Purpose

nag_stat_prob_f (g01ed) returns the probability for the lower or upper tail of the $F$ or variance-ratio distribution with real degrees of freedom.

## Syntax

[result, ifail] = g01ed(f, df1, df2, 'tail', tail)
[result, ifail] = nag_stat_prob_f(f, df1, df2, '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 $F$, or variance-ratio distribution, with ${\nu }_{1}$ and ${\nu }_{2}$ degrees of freedom, $P\left(F\le f:{\nu }_{1},{\nu }_{2}\right)$, is defined by:
 $PF≤f:ν1,ν2=ν1ν1/2ν2ν2/2 Γ ν1+ν2/2 Γν1/2 Γν2/2 ∫0fFν1-2/2ν1F+ν2- ν1+ν2/2dF,$
for ${\nu }_{1}$, ${\nu }_{2}>0$, $f\ge 0$.
The probability is computed by means of a transformation to a beta distribution, ${P}_{\beta }\left(B\le \beta :a,b\right)$:
 $PF≤f:ν1,ν2=Pβ B≤ν1f ν1f+ν2 :ν1/2,ν2/2$
and using a call to nag_stat_prob_beta (g01ee).
For very large values of both ${\nu }_{1}$ and ${\nu }_{2}$, greater than ${10}^{5}$, a normal approximation is used. If only one of ${\nu }_{1}$ or ${\nu }_{2}$ is greater than ${10}^{5}$ then a ${\chi }^{2}$ approximation is used, see Abramowitz and Stegun (1972).

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

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{f}$ – double scalar
$f$, the value of the $F$ variate.
Constraint: ${\mathbf{f}}\ge 0.0$.
2:     $\mathrm{df1}$ – double scalar
The degrees of freedom of the numerator variance, ${\nu }_{1}$.
Constraint: ${\mathbf{df1}}>0.0$.
3:     $\mathrm{df2}$ – double scalar
The degrees of freedom of the denominator variance, ${\nu }_{2}$.
Constraint: ${\mathbf{df2}}>0.0$.

### Optional Input Parameters

1:     $\mathrm{tail}$ – string (length ≥ 1)
Default: $\text{'L'}$
Indicates whether an upper or lower tail probability is required.
${\mathbf{tail}}=\text{'L'}$
The lower tail probability is returned, i.e., $P\left(F\le f:{\nu }_{1},{\nu }_{2}\right)$.
${\mathbf{tail}}=\text{'U'}$
The upper tail probability is returned, i.e., $P\left(F\ge f:{\nu }_{1},{\nu }_{2}\right)$.
Constraint: ${\mathbf{tail}}=\text{'L'}$ or $\text{'U'}$.

### 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_prob_f (g01ed) 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_prob_f (g01ed) returns $0.0$.
${\mathbf{ifail}}=1$
 On entry, ${\mathbf{tail}}\ne \text{'L'}$ or $\text{'U'}$.
${\mathbf{ifail}}=2$
 On entry, ${\mathbf{f}}<0.0$.
${\mathbf{ifail}}=3$
 On entry, ${\mathbf{df1}}\le 0.0$, or ${\mathbf{df2}}\le 0.0$.
${\mathbf{ifail}}=4$
f is too far out into the tails for the probability to be evaluated exactly. The result tends to approach $1.0$ if $f$ is large, or $0.0$ if $f$ is small. The result returned is a good approximation to the required solution.
${\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 result should be accurate to five significant digits.

For higher accuracy nag_stat_prob_beta (g01ee) can be used along with the transformations given in Description.

## Example

This example reads values from, and degrees of freedom for, a number of $F$-distributions and computes the associated lower tail probabilities.
```function g01ed_example

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

% Lower tail probabilities for F distribution
f   = [ 5.5; 39.9;  2.50];
df1 = [ 1.5;  1.0; 20.25];
df2 = [25.5;  1.0;  1.00];
tail = {'Lower'; 'Lower'; 'Lower';};

fprintf('  Tail    F      df1     df2    probability\n');
for j = 1:numel(f);

[p, ifail] = g01ed( ...
f(j), df1(j), df2(j), 'tail', tail{j});

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

```
```g01ed example results

Tail    F      df1     df2    probability
L   5.500     1.5    25.5      0.9837
L  39.900     1.0     1.0      0.9000
L   2.500    20.2     1.0      0.5342
```