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)

 Contents

    1  Purpose
    2  Syntax
    7  Accuracy
    9  Example

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, fpi, associated with the lower tail probability, pi, of the F-distribution with degrees of freedom ui and vi 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 ui,vi>0; 0fpi<.
The value of fpi is computed by means of a transformation to a beta distribution, P iβi Bi βi :ai,bi :
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 ui and vi, greater than 105, a Normal approximation is used. If only one of ui or vi is greater than 105 then a χ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:     tailltail – cell array of strings
Indicates which tail the supplied probabilities represent. For j= i-1 mod ltail +1 , for i=1,2,,maxltail,lp,ldf1,ldf2:
tailj='L'
The lower tail probability, i.e., pi = P Fi fpi : ui , vi .
tailj='U'
The upper tail probability, i.e., pi = P Fi fpi : ui , vi .
Constraint: tailj='L' or 'U', for j=1,2,,ltail.
2:     plp – double array
pi, the probability of the required F-distribution as defined by tail with pi=pj, j=i-1 mod lp+1.
Constraints:
  • if tailk='L', 0.0pj<1.0;
  • otherwise 0.0<pj1.0.
Where k=i-1 mod ltail+1 and j=i-1 mod lp+1.
3:     df1ldf1 – double array
ui, the degrees of freedom of the numerator variance with ui=df1j, j=i-1 mod ldf1+1.
Constraint: df1j>0.0, for j=1,2,,ldf1.
4:     df2ldf2 – double array
vi, the degrees of freedom of the denominator variance with vi=df2j, j=i-1 mod ldf2+1.
Constraint: df2j>0.0, for j=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>0.
2:     lp int64int32nag_int scalar
Default: the dimension of the array p.
The length of the array p.
Constraint: lp>0.
3:     ldf1 int64int32nag_int scalar
Default: the dimension of the array df1.
The length of the array df1.
Constraint: ldf1>0.
4:     ldf2 int64int32nag_int scalar
Default: the dimension of the array df2.
The length of the array df2.
Constraint: ldf2>0.

Output Parameters

1:     f: – double array
The dimension of the array f will be maxltail,lp,ldf1,ldf2
fpi, the deviates for the F-distribution.
2:     ivalid: int64int32nag_int array
The dimension of the array ivalid will be maxltail,lp,ldf1,ldf2
ivalidi indicates any errors with the input arguments, with
ivalidi=0
No error.
ivalidi=1
On entry,invalid value supplied in tail when calculating fpi.
ivalidi=2
On entry,invalid value for pi.
ivalidi=3
On entry,ui0.0,
orvi0.0.
ivalidi=4
The solution has not converged. The result should still be a reasonable approximation to the solution.
ivalidi=5
The value of pi 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:     ifail int64int32nag_int scalar
ifail=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=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=2
Constraint: ltail>0.
   ifail=3
Constraint: lp>0.
   ifail=4
Constraint: ldf1>0.
   ifail=5
Constraint: ldf2>0.
   ifail=-99
An unexpected error has been triggered by this routine. Please contact NAG.
   ifail=-399
Your licence key may have expired or may not have been installed correctly.
   ifail=-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 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

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–2015