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

## Purpose

nag_stat_inv_cdf_beta_vector (g01te) returns a number of deviates associated with given probabilities of the beta distribution.

## Syntax

[beta, ivalid, ifail] = g01te(tail, p, a, b, 'ltail', ltail, 'lp', lp, 'la', la, 'lb', lb, 'tol', tol)
[beta, ivalid, ifail] = nag_stat_inv_cdf_beta_vector(tail, p, a, b, 'ltail', ltail, 'lp', lp, 'la', la, 'lb', lb, 'tol', tol)

## Description

The deviate, ${\beta }_{{p}_{i}}$, associated with the lower tail probability, ${p}_{i}$, of the beta distribution with parameters ${a}_{i}$ and ${b}_{i}$ is defined as the solution to
 $P Bi ≤ βpi :ai,bi = pi = Γ ai + bi Γ ai Γ bi ∫ 0 βpi Bi ai-1 1-Bi bi-1 d Bi , 0 ≤ β pi ≤ 1 ; ​ ai , bi > 0 .$
The algorithm is a modified version of the Newton–Raphson method, following closely that of Cran et al. (1977).
An initial approximation, ${\beta }_{i0}$, to ${\beta }_{{p}_{i}}$ is found (see Cran et al. (1977)), and the Newton–Raphson iteration
 $βk = βk-1 - fi βk-1 fi′ βk-1 ,$
where ${f}_{i}\left({\beta }_{k}\right)=P\left({B}_{i}\le {\beta }_{k}:{a}_{i},{b}_{i}\right)-{p}_{i}$ is used, with modifications to ensure that ${\beta }_{k}$ remains in the range $\left(0,1\right)$.
The input arrays to this function are designed to allow maximum flexibility in the supply of vector arguments by re-using elements of any arrays that are shorter than the total number of evaluations required. See Vectorized Routines in the G01 Chapter Introduction for further information.

## 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{tail}\left({\mathbf{ltail}}\right)$ – cell array of strings
Indicates which tail the supplied probabilities represent. For , for $\mathit{i}=1,2,\dots ,\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{ltail}},{\mathbf{lp}},{\mathbf{la}},{\mathbf{lb}}\right)$:
${\mathbf{tail}}\left(j\right)=\text{'L'}$
The lower tail probability, i.e., ${p}_{i}=P\left({B}_{i}\le {\beta }_{{p}_{i}}:{a}_{i},{b}_{i}\right)$.
${\mathbf{tail}}\left(j\right)=\text{'U'}$
The upper tail probability, i.e., ${p}_{i}=P\left({B}_{i}\ge {\beta }_{{p}_{i}}:{a}_{i},{b}_{i}\right)$.
Constraint: ${\mathbf{tail}}\left(\mathit{j}\right)=\text{'L'}$ or $\text{'U'}$, for $\mathit{j}=1,2,\dots ,{\mathbf{ltail}}$.
2:     $\mathrm{p}\left({\mathbf{lp}}\right)$ – double array
${p}_{i}$, the probability of the required beta distribution as defined by tail with ${p}_{i}={\mathbf{p}}\left(j\right)$, .
Constraint: $0.0\le {\mathbf{p}}\left(\mathit{j}\right)\le 1.0$, for $\mathit{j}=1,2,\dots ,{\mathbf{lp}}$.
3:     $\mathrm{a}\left({\mathbf{la}}\right)$ – double array
${a}_{i}$, the first parameter of the required beta distribution with ${a}_{i}={\mathbf{a}}\left(j\right)$, .
Constraint: $0.0<{\mathbf{a}}\left(\mathit{j}\right)\le {10}^{6}$, for $\mathit{j}=1,2,\dots ,{\mathbf{la}}$.
4:     $\mathrm{b}\left({\mathbf{lb}}\right)$ – double array
${b}_{i}$, the second parameter of the required beta distribution with ${b}_{i}={\mathbf{b}}\left(j\right)$, .
Constraint: $0.0<{\mathbf{b}}\left(\mathit{j}\right)\le {10}^{6}$, for $\mathit{j}=1,2,\dots ,{\mathbf{lb}}$.

### Optional Input Parameters

1:     $\mathrm{ltail}$int64int32nag_int scalar
Default: the dimension of the array tail.
The length of the array tail.
Constraint: ${\mathbf{ltail}}>0$.
2:     $\mathrm{lp}$int64int32nag_int scalar
Default: the dimension of the array p.
The length of the array p.
Constraint: ${\mathbf{lp}}>0$.
3:     $\mathrm{la}$int64int32nag_int scalar
Default: the dimension of the array a.
The length of the array a.
Constraint: ${\mathbf{la}}>0$.
4:     $\mathrm{lb}$int64int32nag_int scalar
Default: the dimension of the array b.
The length of the array b.
Constraint: ${\mathbf{lb}}>0$.
5:     $\mathrm{tol}$ – double scalar
Default: $0.0$
The relative accuracy required by you in the results. If nag_stat_inv_cdf_beta_vector (g01te) 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{beta}\left(:\right)$ – double array
The dimension of the array beta will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{ltail}},{\mathbf{lp}},{\mathbf{la}},{\mathbf{lb}}\right)$
${\beta }_{{p}_{i}}$, the deviates for the beta distribution.
2:     $\mathrm{ivalid}\left(:\right)$int64int32nag_int array
The dimension of the array ivalid will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{ltail}},{\mathbf{lp}},{\mathbf{la}},{\mathbf{lb}}\right)$
${\mathbf{ivalid}}\left(i\right)$ indicates any errors with the input arguments, with
${\mathbf{ivalid}}\left(i\right)=0$
No error.
${\mathbf{ivalid}}\left(i\right)=1$
 On entry, invalid value supplied in tail when calculating ${\beta }_{{p}_{i}}$.
${\mathbf{ivalid}}\left(i\right)=2$
 On entry, ${p}_{i}<0.0$, or ${p}_{i}>1.0$.
${\mathbf{ivalid}}\left(i\right)=3$
 On entry, ${a}_{i}\le 0.0$, or ${a}_{i}>{10}^{6}$, or ${b}_{i}\le 0.0$, or ${b}_{i}>{10}^{6}$.
${\mathbf{ivalid}}\left(i\right)=4$
The solution has not converged but the result should be a reasonable approximation to the solution.
${\mathbf{ivalid}}\left(i\right)=5$
Requested accuracy not achieved when calculating the beta probability. The result should be a reasonable approximation to the correct solution.
3:     $\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_vector (g01te) may return useful information for one or more of the following detected errors or 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  ${\mathbf{ifail}}=1$
On entry, at least one value of tail, p, a, or b was invalid, or the solution failed to converge.
${\mathbf{ifail}}=2$
Constraint: ${\mathbf{ltail}}>0$.
${\mathbf{ifail}}=3$
Constraint: ${\mathbf{lp}}>0$.
${\mathbf{ifail}}=4$
Constraint: ${\mathbf{la}}>0$.
${\mathbf{ifail}}=5$
Constraint: ${\mathbf{lb}}>0$.
${\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_vector (g01se) and will be very dependent on the input argument values. See nag_stat_prob_beta_vector (g01se) for further comments on timings.

## Example

This example reads lower tail probabilities for several beta distributions and calculates and prints the corresponding deviates.
```function g01te_example

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

tail = {'L'};
p = [0.5; 0.99; 0.25];
a = [1.0; 1.5; 20.0];
b = [2.0; 1.5; 10.0];

[x, ivalid, ifail] = g01te( ...
tail, p, a, b);

fprintf('  tail  probability    a         b    deviate    ivalid\n');
ltail = numel(tail);
lp    = numel(p);
la    = numel(a);
lb    = numel(b);
len   = max ([ltail, lp, la, lb]);
for i=0:len-1
fprintf('%5s%9.4f%10.3f%10.3f%10.4f%8d\n', tail{mod(i, ltail)+1}, ...
p(mod(i,lp)+1), a(mod(i,la)+1), b(mod(i,lb)+1), x(i+1), ivalid(i+1));
end

```
```g01te example results

tail  probability    a         b    deviate    ivalid
L   0.5000     1.000     2.000    0.2929       0
L   0.9900     1.500     1.500    0.9672       0
L   0.2500    20.000    10.000    0.6105       0
```