NAG Toolbox: nag_stat_inv_cdf_f_vector (g01td)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

1:     $\mathrm{tail}\left(\mathbf{ltail}\right)$ – cell array of strings

Indicates which tail the supplied probabilities represent. For $j=\left(\left(\mathit{i}-1\right)\mathrm{ mod }\mathbf{ltail}\right)+1$, for $\mathit{i}=1,2,\dots ,\max \left(\mathbf{ltail},\mathbf{lp},\mathbf{ldf1},\mathbf{ldf2}\right)$:

$\mathbf{tail}\left(j\right)=\text{'L'}$

The lower tail probability, i.e., $p_i=P\left(F_i\le f_{p_i}:u_i,v_i\right)$.

$\mathbf{tail}\left(j\right)=\text{'U'}$

The upper tail probability, i.e., $p_i=P\left(F_i\ge f_{p_i}:u_i,v_i\right)$.

Constraint: $\mathbf{tail}\left(\mathit{j}\right)=\text{'L'}$ or $\text{'U'}$, for $\mathit{j}=1,2,\dots ,\mathbf{ltail}$.

2:     $\mathrm{p}\left(\mathbf{lp}\right)$ – double array

$p_i$, the probability of the required $F$-distribution as defined by tail with $p_i=\mathbf{p}\left(j\right)$, $j=\left(\left(i-1\right)\mathrm{ mod }\mathbf{lp}\right)+1$.

Constraints:

• if $\mathbf{tail}\left(k\right)=\text{'L'}$, $0.0\le \mathbf{p}\left(\mathit{j}\right)<1.0$;
• otherwise $0.0<\mathbf{p}\left(\mathit{j}\right)\le 1.0$.

Where $k=\left(i-1\right)\mathrm{ mod }\mathbf{ltail}+1$ and $j=\left(i-1\right)\mathrm{ mod }\mathbf{lp}+1$.

3:     $\mathrm{df1}\left(\mathbf{ldf1}\right)$ – double array

$u_i$, the degrees of freedom of the numerator variance with $u_i=\mathbf{df1}\left(j\right)$, $j=\left(\left(i-1\right)\mathrm{ mod }\mathbf{ldf1}\right)+1$.

Constraint: $\mathbf{df1}\left(\mathit{j}\right)>0.0$, for $\mathit{j}=1,2,\dots ,\mathbf{ldf1}$.

4:     $\mathrm{df2}\left(\mathbf{ldf2}\right)$ – double array

$v_i$, the degrees of freedom of the denominator variance with $v_i=\mathbf{df2}\left(j\right)$, $j=\left(\left(i-1\right)\mathrm{ mod }\mathbf{ldf2}\right)+1$.

Constraint: $\mathbf{df2}\left(\mathit{j}\right)>0.0$, for $\mathit{j}=1,2,\dots ,\mathbf{ldf2}$.

Optional Input Parameters

1:     $\mathrm{ltail}$ – int64int32nag_int scalar

Default: the dimension of the array tail.

The length of the array tail.

Constraint: $\mathbf{ltail}>0$.

2:     $\mathrm{lp}$ – int64int32nag_int scalar

Default: the dimension of the array p.

The length of the array p.

Constraint: $\mathbf{lp}>0$.

3:     $\mathrm{ldf1}$ – int64int32nag_int scalar

Default: the dimension of the array df1.

The length of the array df1.

Constraint: $\mathbf{ldf1}>0$.

4:     $\mathrm{ldf2}$ – int64int32nag_int scalar

Default: the dimension of the array df2.

The length of the array df2.

Constraint: $\mathbf{ldf2}>0$.

Output Parameters

1:     $\mathrm{f}\left(:\right)$ – double array

The dimension of the array f will be $\max \left(\mathbf{ltail},\mathbf{lp},\mathbf{ldf1},\mathbf{ldf2}\right)$

$f_{p_i}$, the deviates for the $F$-distribution.

2:     $\mathrm{ivalid}\left(:\right)$ – int64int32nag_int array

The dimension of the array ivalid will be $\max \left(\mathbf{ltail},\mathbf{lp},\mathbf{ldf1},\mathbf{ldf2}\right)$

$\mathbf{ivalid}\left(i\right)$ indicates any errors with the input arguments, with

$\mathbf{ivalid}\left(i\right)=0$

No error.

$\mathbf{ivalid}\left(i\right)=1$

On entry,

invalid value supplied in tail when calculating $f_{p_i}$.

$\mathbf{ivalid}\left(i\right)=2$

On entry,

invalid value for $p_i$.

$\mathbf{ivalid}\left(i\right)=3$

On entry,	$u_i\le 0.0$,
or	$v_i\le 0.0$.

$\mathbf{ivalid}\left(i\right)=4$

The solution has not converged. The result should still be a reasonable approximation to the solution.

$\mathbf{ivalid}\left(i\right)=5$

The value of $p_i$ is too close to $0.0$ or $1.0$ for the result to be computed. This will only occur when the large sample approximations are used.

3:     $\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.

W  $\mathbf{ifail}=1$

On entry, at least one value of tail, p, df1, df2 was invalid, or the solution failed to converge.
Check ivalid for more information.

   $\mathbf{ifail}=2$

Constraint: $\mathbf{ltail}>0$.

   $\mathbf{ifail}=3$

Constraint: $\mathbf{lp}>0$.

   $\mathbf{ifail}=4$

Constraint: $\mathbf{ldf1}>0$.

   $\mathbf{ifail}=5$

Constraint: $\mathbf{ldf2}>0$.

   $\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: g01td_example

function g01td_example


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

tail = {'L'};
p    = [0.984; 0.9; 0.534];
df1  = [10;    1;  20.25];
df2  = [25.5;  1;   1];

[f, ivalid, ifail] = g01td( ...
                            tail, p, df1, df2);

fprintf('   tail   p      df1     df2      f    ivalid\n');
ltail = numel(tail);
lp    = numel(p);
ldf1  = numel(df1);
ldf2  = numel(df2);
len   = max ([ltail, lp, ldf1, ldf2]);
for i=0:len-1
  fprintf('%5s%7.3f%8.3f%8.3f%8.3f%7d\n', tail{mod(i, ltail)+1}, ...
          p(mod(i,lp)+1), df1(mod(i,ldf1)+1), df2(mod(i,ldf2)+1), ...
          f(i+1), ivalid(i+1));
end

g01td example results

   tail   p      df1     df2      f    ivalid
    L  0.984  10.000  25.500   2.847      0
    L  0.900   1.000   1.000  39.863      0
    L  0.534  20.250   1.000   2.498      0