NAG Toolbox: nag_stat_prob_f_noncentral (g01gd)

Purpose

Syntax

Description

References

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\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 $10\times \mathit{machine precision}$ (see nag_machine_precision (x02aj)), then the value of $10\times \mathit{machine precision}$ 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

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\log \left(U\right)$, where $U=$ 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$

An unexpected error has been triggered by this routine. Please contact NAG.

   $\mathbf{ifail}=-399$

Your licence key may have expired or may not have been installed correctly.

   $\mathbf{ifail}=-999$

Dynamic memory allocation failed.

Accuracy

Further Comments

Example

Open in the MATLAB editor: g01gd_example

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