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_beta (g01fe)

## Purpose

nag_stat_inv_cdf_beta (g01fe) returns the deviate associated with the given lower tail probability of the beta distribution.

## Syntax

[result, ifail] = g01fe(p, a, b, 'tol', tol)
[result, ifail] = nag_stat_inv_cdf_beta(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, ${\beta }_{p}$, associated with the lower tail probability, $p$, of the beta distribution with parameters $a$ and $b$ is defined as the solution to
 $PB≤βp:a,b=p=Γa+b ΓaΓb ∫0βpBa-11-Bb-1dB, 0≤βp≤1;a,b>0.$
The algorithm is a modified version of the Newton–Raphson method, following closely that of Cran et al. (1977).
An initial approximation, ${\beta }_{0}$, to ${\beta }_{p}$ is found (see Cran et al. (1977)), and the Newton–Raphson iteration
 $βi=βi-1-fβi-1 f′βi-1 ,$
where $f\left(\beta \right)=P\left(B\le \beta :a,b\right)-p$ is used, with modifications to ensure that $\beta$ remains in the range $\left(0,1\right)$.

## References

Cran G W, Martin K J and Thomas G E (1977) Algorithm AS 109. Inverse of the incomplete beta function ratio Appl. Statist. 26 111–114
Hastings N A J and Peacock J B (1975) Statistical Distributions Butterworth

## Parameters

### Compulsory Input Parameters

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

### Optional Input Parameters

1:     $\mathrm{tol}$ – double scalar
Default: $0.0$
The relative accuracy required by you in the result. If nag_stat_inv_cdf_beta (g01fe) is entered with tol greater than or equal to $1.0$ or less than  (see nag_machine_precision (x02aj)), then the value of  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_beta (g01fe) 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}}$ or ${\mathbf{2}}$, then nag_stat_inv_cdf_beta (g01fe) 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}}>1.0$.
${\mathbf{ifail}}=2$
 On entry, ${\mathbf{a}}\le 0.0$, or ${\mathbf{a}}>{10}^{6}$, or ${\mathbf{b}}\le 0.0$, or ${\mathbf{b}}>{10}^{6}$.
W  ${\mathbf{ifail}}=3$
There is doubt concerning the accuracy of the computed result. $100$ iterations of the Newton–Raphson method have been performed without satisfying the accuracy criterion (see Accuracy). The result should be a reasonable approximation of the solution.
W  ${\mathbf{ifail}}=4$
Requested accuracy not achieved when calculating beta probability. The result should be a reasonable approximation to the correct solution. You should try setting tol larger.
${\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 required precision, given by tol, should be achieved in most circumstances.

The typical timing will be several times that of nag_stat_prob_beta (g01ee) and will be very dependent on the input argument values. See nag_stat_prob_beta (g01ee) for further comments on timings.

## Example

This example reads lower tail probabilities for several beta distributions and calculates and prints the corresponding deviates until the end of data is reached.
```function g01fe_example

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

p = [    0.50    0.99    0.25];
a = [    1.0     1.5    20.0 ];
b = [    2.0     1.5    10.0 ];
dev  = p;

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

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

```
```g01fe example results

p       a       b    deviate
0.500   1.000   2.000   0.293
0.990   1.500   1.500   0.967
0.250  20.000  10.000   0.611
```