NAG FL Interface
g01tff (inv_cdf_gamma_vector)
1
Purpose
g01tff returns a number of deviates associated with given probabilities of the gamma distribution.
2
Specification
Fortran Interface
Subroutine g01tff ( |
ltail, tail, lp, p, la, a, lb, b, tol, g, ivalid, ifail) |
Integer, Intent (In) |
:: |
ltail, lp, la, lb |
Integer, Intent (Inout) |
:: |
ifail |
Integer, Intent (Out) |
:: |
ivalid(*) |
Real (Kind=nag_wp), Intent (In) |
:: |
p(lp), a(la), b(lb), tol |
Real (Kind=nag_wp), Intent (Out) |
:: |
g(*) |
Character (1), Intent (In) |
:: |
tail(ltail) |
|
C Header Interface
#include <nag.h>
void |
g01tff_ (const Integer *ltail, const char tail[], const Integer *lp, const double p[], const Integer *la, const double a[], const Integer *lb, const double b[], const double *tol, double g[], Integer ivalid[], Integer *ifail, const Charlen length_tail) |
|
C++ Header Interface
#include <nag.h> extern "C" {
void |
g01tff_ (const Integer <ail, const char tail[], const Integer &lp, const double p[], const Integer &la, const double a[], const Integer &lb, const double b[], const double &tol, double g[], Integer ivalid[], Integer &ifail, const Charlen length_tail) |
}
|
The routine may be called by the names g01tff or nagf_stat_inv_cdf_gamma_vector.
3
Description
The deviate,
, associated with the lower tail probability,
, of the gamma distribution with shape parameter
and scale parameter
, is defined as the solution to
The method used is described by
Best and Roberts (1975) making use of the relationship between the gamma distribution and the
-distribution.
Let
. The required
is found from the Taylor series expansion
where
is a starting approximation
- ,
- ,
- ,
- ,
- .
For most values of
and
the starting value
is used, where
is the deviate associated with a lower tail probability of
for the standard Normal distribution.
For
close to zero,
is used.
For large
values, when
,
is found to be a better starting value than
.
For small , is expressed in terms of an approximation to the exponential integral and is found by Newton–Raphson iterations.
Seven terms of the Taylor series are used to refine the starting approximation, repeating the process if necessary until the required accuracy is obtained.
The input arrays to this routine 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
Section 2.6 in the
G01 Chapter Introduction for further information.
4
References
Best D J and Roberts D E (1975) Algorithm AS 91. The percentage points of the distribution Appl. Statist. 24 385–388
5
Arguments
-
1:
– Integer
Input
-
On entry: the length of the array
tail.
Constraint:
.
-
2:
– Character(1) array
Input
-
On entry: indicates which tail the supplied probabilities represent. For
, for
:
- The lower tail probability, i.e., .
- The upper tail probability, i.e., .
Constraint:
or , for .
-
3:
– Integer
Input
-
On entry: the length of the array
p.
Constraint:
.
-
4:
– Real (Kind=nag_wp) array
Input
-
On entry:
, the probability of the required gamma distribution as defined by
tail with
,
.
Constraints:
- if , ;
- otherwise .
Where and .
-
5:
– Integer
Input
-
On entry: the length of the array
a.
Constraint:
.
-
6:
– Real (Kind=nag_wp) array
Input
-
On entry: , the first parameter of the required gamma distribution with , .
Constraint:
, for .
-
7:
– Integer
Input
-
On entry: the length of the array
b.
Constraint:
.
-
8:
– Real (Kind=nag_wp) array
Input
-
On entry: , the second parameter of the required gamma distribution with , .
Constraint:
, for .
-
9:
– Real (Kind=nag_wp)
Input
-
On entry: the relative accuracy required by you in the results. If
g01tff is entered with
tol greater than or equal to
or less than
(see
x02ajf), the value of
is used instead.
-
10:
– Real (Kind=nag_wp) array
Output
-
Note: the dimension of the array
g
must be at least
.
On exit: , the deviates for the gamma distribution.
-
11:
– Integer array
Output
-
Note: the dimension of the array
ivalid
must be at least
.
On exit:
indicates any errors with the input arguments, with
- No error.
- On entry, invalid value supplied in tail when calculating .
- On entry, invalid value for .
- On entry, , or, , or, .
- is too close to or to enable the result to be calculated.
- The solution has failed to converge. The result may be a reasonable approximation.
-
12:
– Integer
Input/Output
-
On entry:
ifail must be set to
,
. If you are unfamiliar with this argument you should refer to
Section 4 in the Introduction to the NAG Library FL Interface for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value
is recommended. If the output of error messages is undesirable, then the value
is recommended. Otherwise, because for this routine the values of the output arguments may be useful even if
on exit, the recommended value is
.
When the value is used it is essential to test the value of ifail on exit.
On exit:
unless the routine detects an error or a warning has been flagged (see
Section 6).
6
Error Indicators and Warnings
If on entry
or
, explanatory error messages are output on the current error message unit (as defined by
x04aaf).
Errors or warnings detected by the routine:
Note: in some cases g01tff may return useful information.
-
On entry, at least one value of
tail,
p,
a, or
b was invalid.
Check
ivalid for more information.
-
On entry, .
Constraint: .
-
On entry, .
Constraint: .
-
On entry, .
Constraint: .
-
On entry, .
Constraint: .
An unexpected error has been triggered by this routine. Please
contact
NAG.
See
Section 7 in the Introduction to the NAG Library FL Interface for further information.
Your licence key may have expired or may not have been installed correctly.
See
Section 8 in the Introduction to the NAG Library FL Interface for further information.
Dynamic memory allocation failed.
See
Section 9 in the Introduction to the NAG Library FL Interface for further information.
7
Accuracy
In most cases the relative accuracy of the results should be as specified by
tol. However, for very small values of
or very small values of
there may be some loss of accuracy.
8
Parallelism and Performance
g01tff is not threaded in any implementation.
None.
10
Example
This example reads lower tail probabilities for several gamma distributions, and calculates and prints the corresponding deviates until the end of data is reached.
10.1
Program Text
10.2
Program Data
10.3
Program Results