hide long namesshow long names
hide short namesshow short names
Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

PDF version (NAG web site, 64-bit version, 64-bit version)
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 FF 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, fpifpi, associated with the lower tail probability, pipi, of the FF-distribution with degrees of freedom uiui and vivi is defined as the solution to
fpi
P( Fi fpi : ui,vi) = pi = ( ui (1/2) ui vi (1/2) vi Γ (( ui + vi )/2) )/( Γ ((ui)/2) Γ ((vi)/2) )Fi (1/2) (ui2) (vi + uiFi) (1/2) (ui + vi) dFi,
0
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 ui,vi > 0ui,vi>0; 0fpi < 0fpi<.
The value of fpifpi is computed by means of a transformation to a beta distribution, Piβi( Bi βi : ai,bi) P iβi ( Bi βi :ai,bi) :
P( Fi fpi : ui,vi) = Piβi( Bi ( ui fpi )/( ui fpi + vi ) : ui / 2 , vi / 2 )
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 uiui and vivi, greater than 105105, a Normal approximation is used. If only one of uiui or vivi is greater than 105105 then a χ2χ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 > 0ltail>0.
Indicates which tail the supplied probabilities represent. For j = ((i1)  mod  ltail) + 1 j= ( (i-1) mod ltail ) +1 , for i = 1,2,,max (ltail,lp,ldf1,ldf2)i=1,2,,max(ltail,lp,ldf1,ldf2):
tail(j) = 'L'tailj='L'
The lower tail probability, i.e., pi = P( Fi fpi : ui , vi ) pi = P( Fi fpi : ui , vi ) .
tail(j) = 'U'tailj='U'
The upper tail probability, i.e., pi = P( Fi fpi : ui , vi ) pi = P( Fi fpi : ui , vi ) .
Constraint: tail(j) = 'L'tailj='L' or 'U''U', for j = 1,2,,ltailj=1,2,,ltail.
2:     p(lp) – double array
lp, the dimension of the array, must satisfy the constraint lp > 0lp>0.
pipi, the probability of the required FF-distribution as defined by tail with pi = p(j)pi=pj, j = ((i1)  mod  lp) + 1j=((i-1) mod lp)+1.
Constraints:
  • if tail(k) = 'L'tailk='L', 0.0p(j) < 1.00.0pj<1.0;
  • otherwise 0.0 < p(j)1.00.0<pj1.0.
Where k = (i1)  mod  ltail + 1 k=(i-1) mod ltail+1 and j = (i1)  mod  lp + 1j=(i-1) mod lp+1.
3:     df1(ldf1) – double array
ldf1, the dimension of the array, must satisfy the constraint ldf1 > 0ldf1>0.
uiui, the degrees of freedom of the numerator variance with ui = df1(j)ui=df1j, j = ((i1)  mod  ldf1) + 1j=((i-1) mod ldf1)+1.
Constraint: df1(j) > 0.0df1j>0.0, for j = 1,2,,ldf1j=1,2,,ldf1.
4:     df2(ldf2) – double array
ldf2, the dimension of the array, must satisfy the constraint ldf2 > 0ldf2>0.
vivi, the degrees of freedom of the denominator variance with vi = df2(j)vi=df2j, j = ((i1)  mod  ldf2) + 1j=((i-1) mod ldf2)+1.
Constraint: df2(j) > 0.0df2j>0.0, for j = 1,2,,ldf2j=1,2,,ldf2.

Optional Input Parameters

1:     ltail – int64int32nag_int scalar
Default: The dimension of the array tail.
The length of the array tail.
Constraint: ltail > 0ltail>0.
2:     lp – int64int32nag_int scalar
Default: The dimension of the array p.
The length of the array p.
Constraint: lp > 0lp>0.
3:     ldf1 – int64int32nag_int scalar
Default: The dimension of the array df1.
The length of the array df1.
Constraint: ldf1 > 0ldf1>0.
4:     ldf2 – int64int32nag_int scalar
Default: The dimension of the array df2.
The length of the array df2.
Constraint: ldf2 > 0ldf2>0.

Input Parameters Omitted from the MATLAB Interface

None.

Output Parameters

1:     f( : :) – double array
Note: the dimension of the array f must be at least max (ltail,lp,ldf1,ldf2)max(ltail,lp,ldf1,ldf2).
fpifpi, the deviates for the FF-distribution.
2:     ivalid( : :) – int64int32nag_int array
Note: the dimension of the array ivalid must be at least max (ltail,lp,ldf1,ldf2)max(ltail,lp,ldf1,ldf2).
ivalid(i)ivalidi indicates any errors with the input arguments, with
ivalid(i) = 0ivalidi=0
No error.
ivalid(i) = 1ivalidi=1
On entry,invalid value supplied in tail when calculating fpifpi.
ivalid(i) = 2ivalidi=2
On entry,invalid value for pipi.
ivalid(i) = 3ivalidi=3
On entry,ui0.0ui0.0,
orvi0.0vi0.0.
ivalid(i) = 4ivalidi=4
The solution has not converged. The result should still be a reasonable approximation to the solution.
ivalid(i) = 5ivalidi=5
The value of pipi is too close to 0.00.0 or 1.01.0 for the result to be computed. This will only occur when the large sample approximations are used.
3:     ifail – int64int32nag_int scalar
ifail = 0ifail=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 ifail = 1ifail=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.
  ifail = 2ifail=2
Constraint: ltail > 0ltail>0.
  ifail = 3ifail=3
Constraint: lp > 0lp>0.
  ifail = 4ifail=4
Constraint: ldf1 > 0ldf1>0.
  ifail = 5ifail=5
Constraint: ldf2 > 0ldf2>0.
  ifail = 999ifail=-999
Dynamic memory allocation failed.

Accuracy

The result should be accurate to five significant digits.

Further Comments

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

Example

function nag_stat_inv_cdf_f_vector_example
tail = {'L'};
p = [0.984; 0.9; 0.534];
df1 = [10; 1; 20.25];
df2 = [25.5; 1; 1];
[f, ivalid, ifail] = nag_stat_inv_cdf_f_vector(tail, p, df1, df2);

fprintf('\n   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('%5c%7.3f%8.3f%8.3f%8.3f%7d\n', cell2mat(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
 

   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

function g01td_example
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('\n   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('%5c%7.3f%8.3f%8.3f%8.3f%7d\n', cell2mat(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
 

   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


PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2013