g01ff: FL CL CPP AD

NAG FL Interface
g01fff (inv_cdf_gamma)

Keyword Search:

NAG Library Manual, Mark 27.1

Interfaces: FL CL CPP AD

NAG FL Interface Introduction

G01 (Stat) Chapter Contents

G01 (Stat) Chapter Introduction

g01ff: FL CL CPP AD

▸▿ Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Parallelism and Performance

9 Further Comments

▸▿ 10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results

1 Purpose

g01fff returns the deviate associated with the given lower tail probability of the gamma distribution.

2 Specification

Fortran Interface

Function g01fff (

p, a, b, tol, ifail)

Real (Kind=nag_wp)	::	g01fff
Integer, Intent (Inout)	::	ifail
Real (Kind=nag_wp), Intent (In)	::	p, a, b, tol

C Header Interface

#include <nag.h>

double

g01fff_ (const double *p, const double *a, const double *b, const double *tol, Integer *ifail)

The routine may be called by the names g01fff or nagf_stat_inv_cdf_gamma.

3 Description

The deviate,

g_{p}

, associated with the lower tail probability,

p

, of the gamma distribution with shape parameter

α

and scale parameter

β

, is defined as the solution to

P (G \leq g_{p} : α, β) = p = \frac{1}{β^{α} Γ (α)} \int_{0}^{g_{p}} e^{- G / β} G^{α - 1} d G, 0 \leq g_{p} < \infty; α, β > 0 .

The method used is described by Best and Roberts (1975) making use of the relationship between the gamma distribution and the

χ^{2}

-distribution.

Let

y = 2 \frac{g_{p}}{β}

. The required

y

is found from the Taylor series expansion

y = y_{0} + \sum_{r} \frac{C_{r} (y_{0})}{r!} {(\frac{E}{ϕ (y_{0})})}^{r},

where

y_{0}

is a starting approximation

$C_{1} (u) = 1$ ,
$C_{r + 1} (u) = (r Ψ + \frac{d}{d u}) C_{r} (u)$ ,
$Ψ = \frac{1}{2} - \frac{α - 1}{u}$ ,
$E = p - \int_{0}^{y_{0}} ϕ (u) d u$ ,
$ϕ (u) = \frac{1}{2^{α} Γ (α)} e^{- u / 2} u^{α - 1}$ .

For most values of

p

and

α

the starting value

y_{01} = 2 α {(z \sqrt{\frac{1}{9 α}} + 1 - \frac{1}{9 α})}^{3}

is used, where

z

is the deviate associated with a lower tail probability of

p

for the standard Normal distribution.

For

p

close to zero,

y_{02} = {(p α 2^{α} Γ (α))}^{1 / α}

is used.

For large

p

values, when

y_{01} > 4.4 α + 6.0

y_{03} = - 2 [\ln (1 - p) - (α - 1) \ln (\frac{1}{2} y_{01}) + \ln (Γ (α))]

is found to be a better starting value than

y_{01}

For small

α

(α \leq 0.16)

p

is expressed in terms of an approximation to the exponential integral and

y_{04}

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.

4 References

Best D J and Roberts D E (1975) Algorithm AS 91. The percentage points of the

χ^{2}

distribution Appl. Statist. 24 385–388

5 Arguments

1: $p$ – Real (Kind=nag_wp) Input: On entry: $p$ , the lower tail probability from the required gamma distribution.

Constraint: $0.0 \leq p < 1.0$ .
2: $a$ – Real (Kind=nag_wp) Input: On entry: $α$ , the shape parameter of the gamma distribution.

Constraint: $0.0 < a \leq 10^{6}$ .
3: $b$ – Real (Kind=nag_wp) Input: On entry: $β$ , the scale parameter of the gamma distribution.

Constraint: $b > 0.0$ .
4: $tol$ – Real (Kind=nag_wp) Input: On entry: the relative accuracy required by you in the results. The smallest recommended value is $50 \times δ$ , where $δ = \max (10^{- 18}, machine precision)$ . If g01fff is entered with tol less than $50 \times δ$ or greater or equal to $1.0$ , then $50 \times δ$ is used instead.
5: $ifail$ – Integer Input/Output: On entry: ifail must be set to $0$ , $- 1$ or $1$ to set behaviour on detection of an error; these values have no effect when no error is detected.
A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $- 1$ means that an error message is printed while a value of $1$ means that it is not.

If halting is not appropriate, the value $- 1$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $- 1$ is recommended since useful values can be provided in some output arguments even when $ifail \neq 0$ on exit. When the value $- 1$ or $1$ is used it is essential to test the value of ifail on exit.

On exit: $ifail = 0$ unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry

ifail = 0

- 1

, 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 g01fff may return useful information.

If on exit

ifail = 1

2

3

5

, then g01fff returns

0.0

$ifail = 1$: On entry, $p = ⟨ value ⟩$ .
Constraint: $p < 1.0$ .

On entry, $p = ⟨ value ⟩$ .
Constraint: $p \geq 0.0$ .

$ifail = 2$: On entry, $a = ⟨ value ⟩$ .
Constraint: $a > 0.0$ .

On entry, $a = ⟨ value ⟩$ .
Constraint: $a \leq 10^{6}$ .

On entry, $b = ⟨ value ⟩$ .
Constraint: $b > 0.0$ .

$ifail = 3$: The probability is too close to $0.0$ for the given a to enable the result to be calculated.

$ifail = 4$: The algorithm has failed to converge in $100$ iterations. A larger value of tol should be tried. The result may be a reasonable approximation.

$ifail = 5$: The series used to calculate the gamma function has failed to converge. This is an unlikely error exit.

$ifail = - 99$: 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.

$ifail = - 399$: 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.

$ifail = - 999$: 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

p

there may be some loss of accuracy.

8 Parallelism and Performance

g01fff is not threaded in any implementation.

9 Further Comments

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.

g01ff: FL CL CPP AD

NAG FL Interfaceg01fff (inv_​cdf_​gamma)

▸▿ Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results

NAG FL Interface
g01fff (inv_cdf_gamma)