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_vector (g01sd)

## Purpose

nag_stat_prob_f_vector (g01sd) returns a number of lower or upper tail probabilities for the F$F$ or variance-ratio distribution with real degrees of freedom.

## Syntax

[p, ivalid, ifail] = g01sd(tail, f, df1, df2, 'ltail', ltail, 'lf', lf, 'ldf1', ldf1, 'ldf2', ldf2)
[p, ivalid, ifail] = nag_stat_prob_f_vector(tail, f, df1, df2, 'ltail', ltail, 'lf', lf, 'ldf1', ldf1, 'ldf2', ldf2)

## Description

The lower tail probability for the F$F$, or variance-ratio, distribution with ui${u}_{i}$ and vi${v}_{i}$ degrees of freedom, P( Fi fi : ui,vi) $P\left({F}_{i}\le {f}_{i}:{u}_{i},{v}_{i}\right)$, is defined by:
 fi P( Fi ≤ fi : ui,vi) = ( uiui / 2 vivi / 2 Γ ((ui + vi) / 2) )/( Γ (ui / 2) Γ (vi / 2) ) ∫ Fi (ui − 2) / 2 (uiFi + vi) − (ui + vi) / 2 dFi, 0
$P( Fi ≤ fi :ui,vi) = ui ui/2 vi vi/2 Γ ( ( ui + vi ) / 2 ) Γ (ui/2) Γ (vi/2) ∫ 0 fi Fi (ui-2) / 2 ( ui Fi + vi ) - ( ui + vi ) / 2 d Fi ,$
for ui${u}_{i}$, vi > 0${v}_{i}>0$, fi0${f}_{i}\ge 0$.
The probability is computed by means of a transformation to a beta distribution, Pβi( Bi βi : ai,bi) ${P}_{{\beta }_{i}}\left({B}_{i}\le {\beta }_{i}:{a}_{i},{b}_{i}\right)$:
 P( Fi ≤ fi : ui,vi) = Pβi( Bi ≤ ( ui fi )/( ui fi + vi ) : ui / 2 , vi / 2 ) $P( Fi ≤ fi :ui,vi) = Pβi( Bi ≤ ui fi ui fi + vi : ui / 2 , vi / 2 )$
and using a call to nag_stat_prob_beta (g01ee).
For very large values of both ui${u}_{i}$ and vi${v}_{i}$, greater than 105${10}^{5}$, a normal approximation is used. If only one of ui${u}_{i}$ or vi${v}_{i}$ is greater than 105${10}^{5}$ then a χ2${\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 parameters by re-using elements of any arrays that are shorter than the total number of evaluations required. See Section [Vectorized s] 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:     tail(ltail) – cell array of strings
ltail, the dimension of the array, must satisfy the constraint ltail > 0${\mathbf{ltail}}>0$.
Indicates whether the lower or upper tail probabilities are required. For j = ((i1)  mod  ltail) + 1 , for i = 1,2,,max (ltail,lf,ldf1,ldf2)$\mathit{i}=1,2,\dots ,\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{ltail}},{\mathbf{lf}},{\mathbf{ldf1}},{\mathbf{ldf2}}\right)$:
tail(j) = 'L'${\mathbf{tail}}\left(j\right)=\text{'L'}$
The lower tail probability is returned, i.e., pi = P( Fi fi : ui,vi) ${p}_{i}=P\left({F}_{i}\le {f}_{i}:{u}_{i},{v}_{i}\right)$.
tail(j) = 'U'${\mathbf{tail}}\left(j\right)=\text{'U'}$
The upper tail probability is returned, i.e., pi = P( Fi fi : ui,vi) ${p}_{i}=P\left({F}_{i}\ge {f}_{i}:{u}_{i},{v}_{i}\right)$.
Constraint: tail(j) = 'L'${\mathbf{tail}}\left(\mathit{j}\right)=\text{'L'}$ or 'U'$\text{'U'}$, for j = 1,2,,ltail$\mathit{j}=1,2,\dots ,{\mathbf{ltail}}$.
2:     f(lf) – double array
lf, the dimension of the array, must satisfy the constraint lf > 0${\mathbf{lf}}>0$.
fi${f}_{i}$, the value of the F$F$ variate with fi = f(j)${f}_{i}={\mathbf{f}}\left(j\right)$, j = ((i1)  mod  lf) + 1.
Constraint: f(j)0.0${\mathbf{f}}\left(\mathit{j}\right)\ge 0.0$, for j = 1,2,,lf$\mathit{j}=1,2,\dots ,{\mathbf{lf}}$.
3:     df1(ldf1) – double array
ldf1, the dimension of the array, must satisfy the constraint ldf1 > 0${\mathbf{ldf1}}>0$.
ui${u}_{i}$, the degrees of freedom of the numerator variance with ui = df1(j)${u}_{i}={\mathbf{df1}}\left(j\right)$, j = ((i1)  mod  ldf1) + 1.
Constraint: df1(j) > 0.0${\mathbf{df1}}\left(\mathit{j}\right)>0.0$, for j = 1,2,,ldf1$\mathit{j}=1,2,\dots ,{\mathbf{ldf1}}$.
4:     df2(ldf2) – double array
ldf2, the dimension of the array, must satisfy the constraint ldf2 > 0${\mathbf{ldf2}}>0$.
vi${v}_{i}$, the degrees of freedom of the denominator variance with vi = df2(j)${v}_{i}={\mathbf{df2}}\left(j\right)$, j = ((i1)  mod  ldf2) + 1.
Constraint: df2(j) > 0.0${\mathbf{df2}}\left(\mathit{j}\right)>0.0$, for j = 1,2,,ldf2$\mathit{j}=1,2,\dots ,{\mathbf{ldf2}}$.

### Optional Input Parameters

1:     ltail – int64int32nag_int scalar
Default: The dimension of the array tail.
The length of the array tail.
Constraint: ltail > 0${\mathbf{ltail}}>0$.
2:     lf – int64int32nag_int scalar
Default: The dimension of the array f.
The length of the array f.
Constraint: lf > 0${\mathbf{lf}}>0$.
3:     ldf1 – int64int32nag_int scalar
Default: The dimension of the array df1.
The length of the array df1.
Constraint: ldf1 > 0${\mathbf{ldf1}}>0$.
4:     ldf2 – int64int32nag_int scalar
Default: The dimension of the array df2.
The length of the array df2.
Constraint: ldf2 > 0${\mathbf{ldf2}}>0$.

None.

### Output Parameters

1:     p( : $:$) – double array
Note: the dimension of the array p must be at least max (ltail,lf,ldf1,ldf2)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{ltail}},{\mathbf{lf}},{\mathbf{ldf1}},{\mathbf{ldf2}}\right)$.
pi${p}_{i}$, the probabilities for the F$F$-distribution.
2:     ivalid( : $:$) – int64int32nag_int array
Note: the dimension of the array ivalid must be at least max (ltail,lf,ldf1,ldf2)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{ltail}},{\mathbf{lf}},{\mathbf{ldf1}},{\mathbf{ldf2}}\right)$.
ivalid(i)${\mathbf{ivalid}}\left(i\right)$ indicates any errors with the input arguments, with
ivalid(i) = 0${\mathbf{ivalid}}\left(i\right)=0$
No error.
ivalid(i) = 1${\mathbf{ivalid}}\left(i\right)=1$
 On entry, invalid value supplied in tail when calculating pi${p}_{i}$.
ivalid(i) = 2${\mathbf{ivalid}}\left(i\right)=2$
 On entry, fi < 0.0${f}_{i}<0.0$.
ivalid(i) = 3${\mathbf{ivalid}}\left(i\right)=3$
 On entry, ui ≤ 0.0${u}_{i}\le 0.0$, or vi ≤ 0.0${v}_{i}\le 0.0$.
ivalid(i) = 4${\mathbf{ivalid}}\left(i\right)=4$
The solution has failed to converge. The result returned should represent an approximation to the solution.
3:     ifail – int64int32nag_int scalar
${\mathrm{ifail}}={\mathbf{0}}$ unless the function detects an error (see [Error Indicators and Warnings]).

## Error Indicators and Warnings

Note: nag_stat_prob_f_vector (g01sd) 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 ifail = 1${\mathbf{ifail}}=1$
On entry, at least one value of f, df1, df2 or tail was invalid, or the solution failed to converge.
ifail = 2${\mathbf{ifail}}=2$
Constraint: ltail > 0${\mathbf{ltail}}>0$.
ifail = 3${\mathbf{ifail}}=3$
Constraint: lf > 0${\mathbf{lf}}>0$.
ifail = 4${\mathbf{ifail}}=4$
Constraint: ldf1 > 0${\mathbf{ldf1}}>0$.
ifail = 5${\mathbf{ifail}}=5$
Constraint: ldf2 > 0${\mathbf{ldf2}}>0$.
ifail = 999${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

## Accuracy

The result should be accurate to five significant digits.

For higher accuracy nag_stat_prob_beta_vector (g01se) can be used along with the transformations given in Section [Description].

## Example

```function nag_stat_prob_f_vector_example
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] = nag_stat_prob_f_vector(tail, f, df1, df2);

fprintf('\n    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  %5d\n', f(mod(i,lf)+1), df1(mod(i,ldf1)+1), ...
df2(mod(i,ldf2)+1), prob(i+1), ivalid(i+1));
end
```
```

F      DF1    DF2     PROB
5.500   1.500  25.500   0.984      0
39.900   1.000   1.000   0.900      0
2.500  20.250   1.000   0.534      0

```
```function g01sd_example
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('\n    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  %5d\n', f(mod(i,lf)+1), df1(mod(i,ldf1)+1), ...
df2(mod(i,ldf2)+1), prob(i+1), ivalid(i+1));
end
```
```

F      DF1    DF2     PROB
5.500   1.500  25.500   0.984      0
39.900   1.000   1.000   0.900      0
2.500  20.250   1.000   0.534      0

```