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_vector (g01sf)

## Purpose

nag_stat_prob_gamma_vector (g01sf) returns a number of lower or upper tail probabilities for the gamma distribution.

## Syntax

[p, ivalid, ifail] = g01sf(tail, g, a, b, 'ltail', ltail, 'lg', lg, 'la', la, 'lb', lb)
[p, ivalid, ifail] = nag_stat_prob_gamma_vector(tail, g, a, b, 'ltail', ltail, 'lg', lg, 'la', la, 'lb', lb)

## Description

The lower tail probability for the gamma distribution with parameters αi${\alpha }_{i}$ and βi${\beta }_{i}$, P(Gigi)$P\left({G}_{i}\le {g}_{i}\right)$, is defined by:
 gi P( Gi ≤ gi : αi,βi) = 1/( βiαi Γ (αi) ) ∫ Giαi − 1e − Gi / βidGi,  αi > 0.0, ​βi > 0.0. 0
$P( Gi ≤ gi :αi,βi) = 1 βi αi Γ (αi) ∫ 0 gi Gi αi-1 e -Gi/βi dGi , αi>0.0 , ​ βi>0.0 .$
The mean of the distribution is αiβi${\alpha }_{i}{\beta }_{i}$ and its variance is αiβi2${\alpha }_{i}{{\beta }_{i}}^{2}$. The transformation Zi = (Gi)/(βi)${Z}_{i}=\frac{{G}_{i}}{{\beta }_{i}}$ is applied to yield the following incomplete gamma function in normalized form,
 gi / βi P( Gi ≤ gi : αi,βi) = P( Zi ≤ gi / βi : αi,1.0) = 1/( Γ (αi) ) ∫ Ziαi − 1e − ZidZi. 0
$P( Gi ≤ gi :αi,βi) = P( Zi ≤ gi / βi :αi,1.0) = 1 Γ (αi) ∫ 0 gi / βi Zi αi-1 e -Zi dZi .$
This is then evaluated using nag_specfun_gamma_incomplete (s14ba).
The input arrays to this function are designed to allow maximum flexibility in the supply of vector parameters by re-using elements of any arrays that are shorter than the total number of evaluations required. See Section [Vectorized s] in the G01 Chapter Introduction for further information.

## References

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

## Parameters

### Compulsory Input Parameters

1:     tail(ltail) – cell array of strings
ltail, the dimension of the array, must satisfy the constraint ltail > 0${\mathbf{ltail}}>0$.
Indicates whether a lower or upper tail probability is required. For j = ((i1)  mod  ltail) + 1 , for i = 1,2,,max (ltail,lg,la,lb)$\mathit{i}=1,2,\dots ,\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{ltail}},{\mathbf{lg}},{\mathbf{la}},{\mathbf{lb}}\right)$:
tail(j) = 'L'${\mathbf{tail}}\left(j\right)=\text{'L'}$
The lower tail probability is returned, i.e., pi = P( Gi gi : αi,βi) ${p}_{i}=P\left({G}_{i}\le {g}_{i}:{\alpha }_{i},{\beta }_{i}\right)$.
tail(j) = 'U'${\mathbf{tail}}\left(j\right)=\text{'U'}$
The upper tail probability is returned, i.e., pi = P( Gi gi : αi,βi) ${p}_{i}=P\left({G}_{i}\ge {g}_{i}:{\alpha }_{i},{\beta }_{i}\right)$.
Constraint: tail(j) = 'L'${\mathbf{tail}}\left(\mathit{j}\right)=\text{'L'}$ or 'U'$\text{'U'}$, for j = 1,2,,ltail$\mathit{j}=1,2,\dots ,{\mathbf{ltail}}$.
2:     g(lg) – double array
lg, the dimension of the array, must satisfy the constraint lg > 0${\mathbf{lg}}>0$.
gi${g}_{i}$, the value of the gamma variate with gi = g(j)${g}_{i}={\mathbf{g}}\left(j\right)$, j = ((i1)  mod  lg) + 1.
Constraint: g(j)0.0${\mathbf{g}}\left(\mathit{j}\right)\ge 0.0$, for j = 1,2,,lg$\mathit{j}=1,2,\dots ,{\mathbf{lg}}$.
3:     a(la) – double array
la, the dimension of the array, must satisfy the constraint la > 0${\mathbf{la}}>0$.
The parameter αi${\alpha }_{i}$ of the gamma distribution with αi = a(j)${\alpha }_{i}={\mathbf{a}}\left(j\right)$, j = ((i1)  mod  la) + 1.
Constraint: a(j) > 0.0${\mathbf{a}}\left(\mathit{j}\right)>0.0$, for j = 1,2,,la$\mathit{j}=1,2,\dots ,{\mathbf{la}}$.
4:     b(lb) – double array
lb, the dimension of the array, must satisfy the constraint lb > 0${\mathbf{lb}}>0$.
The parameter βi${\beta }_{i}$ of the gamma distribution with βi = b(j)${\beta }_{i}={\mathbf{b}}\left(j\right)$, j = ((i1)  mod  lb) + 1.
Constraint: b(j) > 0.0${\mathbf{b}}\left(\mathit{j}\right)>0.0$, for j = 1,2,,lb$\mathit{j}=1,2,\dots ,{\mathbf{lb}}$.

### Optional Input Parameters

1:     ltail – int64int32nag_int scalar
Default: The dimension of the array tail.
The length of the array tail.
Constraint: ltail > 0${\mathbf{ltail}}>0$.
2:     lg – int64int32nag_int scalar
Default: The dimension of the array g.
The length of the array g.
Constraint: lg > 0${\mathbf{lg}}>0$.
3:     la – int64int32nag_int scalar
Default: The dimension of the array a.
The length of the array a.
Constraint: la > 0${\mathbf{la}}>0$.
4:     lb – int64int32nag_int scalar
Default: The dimension of the array b.
The length of the array b.
Constraint: lb > 0${\mathbf{lb}}>0$.

None.

### Output Parameters

1:     p( : $:$) – double array
Note: the dimension of the array p must be at least max (lg,la,lb,ltail)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{lg}},{\mathbf{la}},{\mathbf{lb}},{\mathbf{ltail}}\right)$.
pi${p}_{i}$, the probabilities of the beta distribution.
2:     ivalid( : $:$) – int64int32nag_int array
Note: the dimension of the array ivalid must be at least max (lg,la,lb,ltail)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{lg}},{\mathbf{la}},{\mathbf{lb}},{\mathbf{ltail}}\right)$.
ivalid(i)${\mathbf{ivalid}}\left(i\right)$ indicates any errors with the input arguments, with
ivalid(i) = 0${\mathbf{ivalid}}\left(i\right)=0$
No error.
ivalid(i) = 1${\mathbf{ivalid}}\left(i\right)=1$
 On entry, invalid value supplied in tail when calculating pi${p}_{i}$.
ivalid(i) = 2${\mathbf{ivalid}}\left(i\right)=2$
 On entry, gi < 0.0${g}_{i}<0.0$.
ivalid(i) = 3${\mathbf{ivalid}}\left(i\right)=3$
 On entry, αi ≤ 0.0${\alpha }_{i}\le 0.0$, or βi ≤ 0.0${\beta }_{i}\le 0.0$.
ivalid(i) = 4${\mathbf{ivalid}}\left(i\right)=4$
The solution did not converge in 600$600$ iterations, see nag_specfun_gamma_incomplete (s14ba) for details. The probability returned should be a reasonable approximation to the solution.
3:     ifail – int64int32nag_int scalar
${\mathrm{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:

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${\mathbf{ifail}}=1$
On entry, at least one value of g, a, b or tail was invalid, or the solution did not converge.
ifail = 2${\mathbf{ifail}}=2$
Constraint: ltail > 0${\mathbf{ltail}}>0$.
ifail = 3${\mathbf{ifail}}=3$
Constraint: lg > 0${\mathbf{lg}}>0$.
ifail = 4${\mathbf{ifail}}=4$
Constraint: la > 0${\mathbf{la}}>0$.
ifail = 5${\mathbf{ifail}}=5$
Constraint: lb > 0${\mathbf{lb}}>0$.
ifail = 999${\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$1$ or 2$2$ decimal places.

The time taken by nag_stat_prob_gamma_vector (g01sf) to calculate each probability varies slightly with the input parameters gi${g}_{i}$, αi${\alpha }_{i}$ and βi${\beta }_{i}$.

## Example

```function nag_stat_prob_gamma_vector_example
tail = {'L'};
g = [15.5; 0.5; 10; 5];
a = [4; 4; 1; 2];
b = [2; 1; 2; 2];
% calculate probability
[p, ivalid, ifail] = nag_stat_prob_gamma_vector(tail, g, a, b);

fprintf('\nGamma deviate    Alpha     Beta    Probability\n');
lg = numel(g);
la = numel(a);
lb = numel(b);
ltail = numel(tail);
len = max ([lg, la, lb, ltail]);
for i=0:len-1
fprintf('%9.2f%13.2f%9.2f%10.4f%8d\n', g(mod(i,lg)+1), a(mod(i,la)+1), ...
b(mod(i,lb)+1), p(i+1), ivalid(i+1));
end
```
```

Gamma deviate    Alpha     Beta    Probability
15.50         4.00     2.00    0.9499       0
0.50         4.00     1.00    0.0018       0
10.00         1.00     2.00    0.9933       0
5.00         2.00     2.00    0.7127       0

```
```function g01sf_example
tail = {'L'};
g = [15.5; 0.5; 10; 5];
a = [4; 4; 1; 2];
b = [2; 1; 2; 2];
% calculate probability
[p, ivalid, ifail] = g01sf(tail, g, a, b);

fprintf('\nGamma deviate    Alpha     Beta    Probability\n');
lg = numel(g);
la = numel(a);
lb = numel(b);
ltail = numel(tail);
len = max ([lg, la, lb, ltail]);
for i=0:len-1
fprintf('%9.2f%13.2f%9.2f%10.4f%8d\n', g(mod(i,lg)+1), a(mod(i,la)+1), ...
b(mod(i,lb)+1), p(i+1), ivalid(i+1));
end
```
```

Gamma deviate    Alpha     Beta    Probability
15.50         4.00     2.00    0.9499       0
0.50         4.00     1.00    0.0018       0
10.00         1.00     2.00    0.9933       0
5.00         2.00     2.00    0.7127       0

```