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_prob_gamma (g01ef)

## Purpose

nag_stat_prob_gamma (g01ef) returns the lower or upper tail probability of the gamma distribution, with parameters $\alpha$ and $\beta$.

## Syntax

[result, ifail] = g01ef(g, a, b, 'tail', tail)
[result, ifail] = nag_stat_prob_gamma(g, a, b, 'tail', tail)
Note: the interface to this routine has changed since earlier releases of the toolbox:
 At Mark 23: tail was made optional (default 'L')

## Description

The lower tail probability for the gamma distribution with parameters $\alpha$ and $\beta$, $P\left(G\le g\right)$, is defined by:
 $P G≤g ; α,β = 1 βα Γα ∫0g Gα-1 e-G/β dG , α>0.0 , ​ β>0.0 .$
The mean of the distribution is $\alpha \beta$ and its variance is $\alpha {\beta }^{2}$. The transformation $Z=\frac{G}{\beta }$ is applied to yield the following incomplete gamma function in normalized form,
 $P G≤g ; α ,β = P Z≤g/β : α,1.0 = 1 Γα ∫0g/β Zα-1 e-Z dZ .$
This is then evaluated using nag_specfun_gamma_incomplete (s14ba).

## References

Hastings N A J and Peacock J B (1975) Statistical Distributions Butterworth

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{g}$ – double scalar
$g$, the value of the gamma variate.
Constraint: ${\mathbf{g}}\ge 0.0$.
2:     $\mathrm{a}$ – double scalar
The parameter $\alpha$ of the gamma distribution.
Constraint: ${\mathbf{a}}>0.0$.
3:     $\mathrm{b}$ – double scalar
The parameter $\beta$ of the gamma distribution.
Constraint: ${\mathbf{b}}>0.0$.

### Optional Input Parameters

1:     $\mathrm{tail}$ – string (length ≥ 1)
Default: $\text{'L'}$
Indicates whether an upper or lower tail probability is required.
${\mathbf{tail}}=\text{'L'}$
The lower tail probability is returned, that is $P\left(G\le g:\alpha ,\beta \right)$.
${\mathbf{tail}}=\text{'U'}$
The upper tail probability is returned, that is $P\left(G\ge g:\alpha ,\beta \right)$.
Constraint: ${\mathbf{tail}}=\text{'L'}$ or $\text{'U'}$.

### 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

Errors or warnings detected by the function:
If ${\mathbf{ifail}}={\mathbf{1}}$, ${\mathbf{2}}$, ${\mathbf{3}}$ or ${\mathbf{4}}$ on exit, then nag_stat_prob_gamma (g01ef) 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{tail}}\ne \text{'L'}$ or $\text{'U'}$.
${\mathbf{ifail}}=2$
 On entry, ${\mathbf{g}}<0.0$.
${\mathbf{ifail}}=3$
 On entry, ${\mathbf{a}}\le 0.0$, or ${\mathbf{b}}\le 0.0$.
W  ${\mathbf{ifail}}=4$
The solution did not converge in $600$ iterations. See nag_specfun_gamma_incomplete (s14ba). The probability returned should be a reasonable approximation to the solution.
${\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

The result should have a relative accuracy of machine precision. There are rare occasions when the relative accuracy attained is somewhat less than machine precision but the error should not exceed more than $1$ or $2$ decimal places. Note also that there is a limit of $18$ decimal places on the achievable accuracy, because constants in nag_specfun_gamma_incomplete (s14ba) are given to this precision.

The time taken by nag_stat_prob_gamma (g01ef) varies slightly with the input arguments g, a and b.

## Example

This example reads in values from a number of gamma distributions and computes the associated lower tail probabilities.
```function g01ef_example

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

% Lower tail probabilities for Gamma distribution
g    = [   15.5;     0.5;    10.0;     5.0];
a    = [    4.0;     4.0;     1.0;     2.0];
b    = [    2.0;     1.0;     2.0;     2.0];
tail = {'Lower'; 'Lower'; 'Lower'; 'Lower'};

fprintf('  Tail    G      a      b     probability\n');
for j = 1:numel(g);

[p, ifail] = g01ef( ...
g(j), a(j), b(j), 'tail', tail{j});

fprintf('%4s%8.2f%8.2f%8.2f%12.4f\n', tail{j}(1), g(j), a(j), b(j), p);
end

```
```g01ef example results

Tail    G      a      b     probability
L   15.50    4.00    2.00      0.9499
L    0.50    4.00    1.00      0.0018
L   10.00    1.00    2.00      0.9933
L    5.00    2.00    2.00      0.7127
```