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_inv_cdf_gamma (g01ff)

## Purpose

nag_stat_inv_cdf_gamma (g01ff) returns the deviate associated with the given lower tail probability of the gamma distribution.

## Syntax

[result, ifail] = g01ff(p, a, b, 'tol', tol)
[result, ifail] = nag_stat_inv_cdf_gamma(p, a, b, 'tol', tol)
Note: the interface to this routine has changed since earlier releases of the toolbox:
 At Mark 23: tol was made optional (default 0)

## Description

The deviate, ${g}_{p}$, associated with the lower tail probability, $p$, of the gamma distribution with shape parameter $\alpha$ and scale parameter $\beta$, is defined as the solution to
 $PG≤gp:α,β=p=1βαΓα ∫0gpe-G/βGα-1dG, 0≤gp<∞;α,β>0.$
The method used is described by Best and Roberts (1975) making use of the relationship between the gamma distribution and the ${\chi }^{2}$-distribution.
Let $y=2\frac{{g}_{p}}{\beta }$. The required $y$ is found from the Taylor series expansion
 $y=y0+∑rCry0 r! Eϕy0 r,$
where ${y}_{0}$ is a starting approximation
• ${C}_{1}\left(u\right)=1$,
• ${C}_{r+1}\left(u\right)=\left(r\Psi +\frac{d}{du}\right){C}_{r}\left(u\right)$,
• $\Psi =\frac{1}{2}-\frac{\alpha -1}{u}$,
• $E=p-\underset{0}{\overset{{y}_{0}}{\int }}\varphi \left(u\right)du$,
• $\varphi \left(u\right)=\frac{1}{{2}^{\alpha }\Gamma \left(\alpha \right)}{e}^{-u/2}{u}^{\alpha -1}$.
For most values of $p$ and $\alpha$ the starting value
 $y01=2α z⁢19α +1-19α 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,
 $y02= pα2αΓ α 1/α$
is used.
For large $p$ values, when ${y}_{01}>4.4\alpha +6.0$,
 $y03=-2ln1-p-α-1ln12y01+lnΓ α$
is found to be a better starting value than ${y}_{01}$.
For small $\alpha$ $\left(\alpha \le 0.16\right)$, $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.

## References

Best D J and Roberts D E (1975) Algorithm AS 91. The percentage points of the ${\chi }^{2}$ distribution Appl. Statist. 24 385–388

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{p}$ – double scalar
$p$, the lower tail probability from the required gamma distribution.
Constraint: $0.0\le {\mathbf{p}}<1.0$.
2:     $\mathrm{a}$ – double scalar
$\alpha$, the shape parameter of the gamma distribution.
Constraint: $0.0<{\mathbf{a}}\le {10}^{6}$.
3:     $\mathrm{b}$ – double scalar
$\beta$, the scale parameter of the gamma distribution.
Constraint: ${\mathbf{b}}>0.0$.

### Optional Input Parameters

1:     $\mathrm{tol}$ – double scalar
Default: $0.0$
The relative accuracy required by you in the results. The smallest recommended value is $50×\delta$, where . If nag_stat_inv_cdf_gamma (g01ff) is entered with tol less than $50×\delta$ or greater or equal to $1.0$, then $50×\delta$ is used instead.

### Output Parameters

1:     $\mathrm{result}$ – double scalar
The result of the function.
2:     $\mathrm{ifail}$int64int32nag_int scalar
${\mathbf{ifail}}={\mathbf{0}}$ unless the function detects an error (see Error Indicators and Warnings).

## Error Indicators and Warnings

Note: nag_stat_inv_cdf_gamma (g01ff) may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the function:
If on exit ${\mathbf{ifail}}={\mathbf{1}}$, ${\mathbf{2}}$, ${\mathbf{3}}$ or ${\mathbf{5}}$, then nag_stat_inv_cdf_gamma (g01ff) returns $0.0$.

Cases prefixed with W are classified as warnings and do not generate an error of type NAG:error_n. See nag_issue_warnings.

${\mathbf{ifail}}=1$
 On entry, ${\mathbf{p}}<0.0$, or ${\mathbf{p}}\ge 1.0$,
${\mathbf{ifail}}=2$
 On entry, ${\mathbf{a}}\le 0.0$, or ${\mathbf{a}}>{10}^{6}$, or ${\mathbf{b}}\le 0.0$
${\mathbf{ifail}}=3$
p is too close to $0.0$ or $1.0$ to enable the result to be calculated.
W  ${\mathbf{ifail}}=4$
The solution has failed to converge in $100$ iterations. A larger value of tol should be tried. The result may be a reasonable approximation.
${\mathbf{ifail}}=5$
The series to calculate the gamma function has failed to converge. This is an unlikely error exit.
${\mathbf{ifail}}=-99$
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

## Accuracy

In most cases the relative accuracy of the results should be as specified by tol. However, for very small values of $\alpha$ or very small values of $p$ there may be some loss of accuracy.

None.

## 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.
```function g01ff_example

fprintf('g01ff example results\n\n');

p = [  0.01    0.428   0.869 ];
a = [  1       7.5    45     ];
b = [ 20       0.1    10     ];
x  = p;

fprintf('     p       a       b       x\n');
for j = 1:numel(p)
[x(j), ifail] = g01ff( ...
p(j), a(j), b(j));
end

fprintf('%8.3f%8.3f%8.3f%8.3f\n', [p; a; b; x]);

```
```g01ff example results

p       a       b       x
0.010   1.000  20.000   0.201
0.428   7.500   0.100   0.670
0.869  45.000  10.000 525.839
```