NAG Toolbox: nag_stat_prob_f_vector (g01sd)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

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

Indicates whether the lower or upper tail probabilities are required. 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{lf},\mathbf{ldf1},\mathbf{ldf2}\right)$:

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

The lower tail probability is returned, i.e., $p_i=P\left(F_i\le f_i:u_i,v_i\right)$.

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

The upper tail probability is returned, i.e., $p_i=P\left(F_i\ge f_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{f}\left(\mathbf{lf}\right)$ – double array

$f_i$, the value of the $F$ variate with $f_i=\mathbf{f}\left(j\right)$, $j=\left(\left(i-1\right)\mathrm{ mod }\mathbf{lf}\right)+1$.

Constraint: $\mathbf{f}\left(\mathit{j}\right)\ge 0.0$, for $\mathit{j}=1,2,\dots ,\mathbf{lf}$.

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{lf}$ – int64int32nag_int scalar

Default: the dimension of the array f.

The length of the array f.

Constraint: $\mathbf{lf}>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{p}\left(:\right)$ – double array

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

$p_i$, the probabilities 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{lf},\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 $p_i$.

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

On entry,

$f_i<0.0$.

$\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 failed to converge. The result returned should represent an approximation to the solution.

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 f, df1, df2 or tail 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{lf}>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: g01sd_example

function g01sd_example


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

f = [5.5; 39.9; 2.5];
df1 = [1.5; 1; 20.25];
df2 = [25.5; 1; 1];
tail = {'L'};
% calculate probability
[prob, ivalid, ifail] = g01sd( ...
                               tail, f, df1, df2);

fprintf('    F       df1    df2     prob\n');
lf    = numel(f);
ldf1  = numel(df1);
ldf2  = numel(df2);
ltail = numel(tail);
len   = max ([lf, ldf1, ldf2, ltail]);
for i=0:len-1
  fprintf('%7.3f%8.3f%8.3f%8.3f\n', f(mod(i,lf)+1), df1(mod(i,ldf1)+1), ...
          df2(mod(i,ldf2)+1), prob(i+1));
end

g01sd example results

    F       df1    df2     prob
  5.500   1.500  25.500   0.984
 39.900   1.000   1.000   0.900
  2.500  20.250   1.000   0.534