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_inv_cdf_f_vector (g01td)

## Purpose

nag_stat_inv_cdf_f_vector (g01td) returns a number of deviates associated with given probabilities of the $F$ or variance-ratio distribution with real degrees of freedom.

## Syntax

[f, ivalid, ifail] = g01td(tail, p, df1, df2, 'ltail', ltail, 'lp', lp, 'ldf1', ldf1, 'ldf2', ldf2)
[f, ivalid, ifail] = nag_stat_inv_cdf_f_vector(tail, p, df1, df2, 'ltail', ltail, 'lp', lp, 'ldf1', ldf1, 'ldf2', ldf2)

## Description

The deviate, ${f}_{{p}_{i}}$, associated with the lower tail probability, ${p}_{i}$, of the $F$-distribution with degrees of freedom ${u}_{i}$ and ${v}_{i}$ is defined as the solution to
 $P Fi ≤ fpi :ui,vi = pi = u i 12 ui v i 12 vi Γ ui + vi 2 Γ ui 2 Γ vi 2 ∫ 0 fpi Fi 12 ui-2 vi + ui Fi -12 ui + vi dFi ,$
where ${u}_{i},{v}_{i}>0$; $0\le {f}_{{p}_{i}}<\infty$.
The value of ${f}_{{p}_{i}}$ is computed by means of a transformation to a beta distribution, ${P}_{i{\beta }_{i}}\left({B}_{i}\le {\beta }_{i}:{a}_{i},{b}_{i}\right)$:
 $P Fi ≤ fpi :ui,vi = P iβi Bi ≤ ui fpi ui fpi + vi : ui / 2 , vi / 2$
and using a call to nag_stat_inv_cdf_beta_vector (g01te).
For very large values of both ${u}_{i}$ and ${v}_{i}$, greater than ${10}^{5}$, a Normal approximation is used. If only one of ${u}_{i}$ or ${v}_{i}$ is greater than ${10}^{5}$ then a ${\chi }^{2}$ approximation is used; see Abramowitz and Stegun (1972).
The input arrays to this function are designed to allow maximum flexibility in the supply of vector arguments by re-using elements of any arrays that are shorter than the total number of evaluations required. See Vectorized Routines in the G01 Chapter Introduction for further information.

## 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{tail}\left({\mathbf{ltail}}\right)$ – cell array of strings
Indicates which tail the supplied probabilities represent. For , for $\mathit{i}=1,2,\dots ,\mathrm{max}\phantom{\rule{0.125em}{0ex}}\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)$, .
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  and .
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)$, .
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)$, .
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 $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\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 $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\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

Note: nag_stat_inv_cdf_f_vector (g01td) may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the function:

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.
${\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$
${\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_inv_cdf_beta_vector (g01te) can be used along with the transformations given in Description.

## Example

This example reads the lower tail probabilities for several $F$-distributions, and calculates and prints the corresponding deviates.
```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
```