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_noncentral (g01gd)

## Purpose

nag_stat_prob_f_noncentral (g01gd) returns the probability associated with the lower tail of the noncentral $F$ or variance-ratio distribution.

## Syntax

[result, ifail] = g01gd(f, df1, df2, rlamda, 'tol', tol, 'maxit', maxit)
[result, ifail] = nag_stat_prob_f_noncentral(f, df1, df2, rlamda, 'tol', tol, 'maxit', maxit)
Note: the interface to this routine has changed since earlier releases of the toolbox:
 At Mark 23: tol was made optional (default 0)

## Description

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.

## References

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

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{f}$ – double scalar
$f$, the deviate from the noncentral $F$-distribution.
Constraint: ${\mathbf{f}}>0.0$.
2:     $\mathrm{df1}$ – double scalar
The degrees of freedom of the numerator variance, ${\nu }_{1}$.
Constraint: $0.0<{\mathbf{df1}}\le {10}^{6}$.
3:     $\mathrm{df2}$ – double scalar
The degrees of freedom of the denominator variance, ${\nu }_{2}$.
Constraint: ${\mathbf{df2}}>0.0$.
4:     $\mathrm{rlamda}$ – double scalar
$\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 nag_machine_real_safe (x02am).

### Optional Input Parameters

1:     $\mathrm{tol}$ – double scalar
Default: $0.0$
The relative accuracy required by you in the results. If nag_stat_prob_f_noncentral (g01gd) is entered with tol greater than or equal to $1.0$ or less than  (see nag_machine_precision (x02aj)), then the value of  is used instead.
2:     $\mathrm{maxit}$int64int32nag_int scalar
Default: $500$. See nag_stat_prob_chisq_noncentral (g01gc) and nag_stat_prob_beta_noncentral (g01ge) for further details.
The maximum number of iterations to be used.
Constraint: ${\mathbf{maxit}}\ge 1$.

### 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_noncentral (g01gd) may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the function:
If on exit ${\mathbf{ifail}}={\mathbf{1}}$ or ${\mathbf{3}}$, then nag_stat_prob_f_noncentral (g01gd) returns $0.0$.

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{df1}}\le 0.0$, or ${\mathbf{df1}}>{10}^{6}$, or ${\mathbf{df2}}\le 0.0$, or ${\mathbf{f}}\le 0.0$, or ${\mathbf{rlamda}}<0.0$, or ${\mathbf{maxit}}<1$, or ${\mathbf{rlamda}}>-2.0\mathrm{log}\left(U\right)$, where $U=\text{}$ safe range argument as defined by nag_machine_real_safe (x02am).
${\mathbf{ifail}}=2$
The solution has failed to converge in maxit iterations. You should try a larger value of maxit or tol.
${\mathbf{ifail}}=3$
The required probability cannot be computed accurately. This may happen if the result would be very close to $0.0$ or $1.0$. 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).
W  ${\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 nag_stat_prob_f_noncentral (g01gd) returns zero otherwise the value returned should be an 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 relative accuracy should be as specified by tol. For further details see nag_stat_prob_chisq_noncentral (g01gc) and nag_stat_prob_beta_noncentral (g01ge).

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.

## Example

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.
```function g01gd_example

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

f      = [  5.5     39.9     2.5 ];
df1    = [  1.5      1      20.25];
df2    = [ 25.5      1       1   ];
rlamda = [  3        2       0   ];
p      = f;

fprintf('     f      df1     df2    rlamda     p\n');
for j = 1:numel(f)
[p(j), ifail] = g01gd( ...
f(j), df1(j), df2(j), rlamda(j));
end

fprintf('%8.3f%8.3f%8.3f%8.3f%8.4f\n', [f; df1; df2; rlamda; p]);

```
```g01gd example results

f      df1     df2    rlamda     p
5.500   1.500  25.500   3.000  0.8214
39.900   1.000   1.000   2.000  0.8160
2.500  20.250   1.000   0.000  0.5342
```