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, βpi${\beta }_{{p}_{i}}$, associated with the lower tail probability, pi${p}_{i}$, of the beta distribution with parameters ai${a}_{i}$ and bi${b}_{i}$ is defined as the solution to
 βpi P( Bi ≤ βpi : ai,bi) = pi = ( Γ (ai + bi) )/( Γ (ai) Γ (bi) ) ∫ Biai − 1(1 − Bi)bi − 1 d Bi ,  0 ≤ βpi ≤ 1; ​ai,bi > 0. 0
$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, βi0${\beta }_{i0}$, to βpi${\beta }_{{p}_{i}}$ is found (see Cran et al. (1977)), and the Newton–Raphson iteration
 βk = βk − 1 − ( fi (βk − 1) )/( fi′ (βk − 1) ) , $βk = βk-1 - fi ( βk-1 ) fi′ ( βk-1 ) ,$
where fi (βk) = P( Bi βk : ai,bi) pi ${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 βk${\beta }_{k}$ remains in the range (0,1)$\left(0,1\right)$.
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

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:     tail(ltail) – cell array of strings
ltail, the dimension of the array, must satisfy the constraint ltail > 0${\mathbf{ltail}}>0$.
Indicates which tail the supplied probabilities represent. For j = ((i1)  mod  ltail) + 1 , for i = 1,2,,max (ltail,lp,la,lb)$\mathit{i}=1,2,\dots ,\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{ltail}},{\mathbf{lp}},{\mathbf{la}},{\mathbf{lb}}\right)$:
tail(j) = 'L'${\mathbf{tail}}\left(j\right)=\text{'L'}$
The lower tail probability, i.e., pi = P( Bi βpi : ai , bi ) ${p}_{i}=P\left({B}_{i}\le {\beta }_{{p}_{i}}:{a}_{i},{b}_{i}\right)$.
tail(j) = 'U'${\mathbf{tail}}\left(j\right)=\text{'U'}$
The upper tail probability, i.e., pi = P( Bi βpi : ai , bi ) ${p}_{i}=P\left({B}_{i}\ge {\beta }_{{p}_{i}}:{a}_{i},{b}_{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:     p(lp) – double array
lp, the dimension of the array, must satisfy the constraint lp > 0${\mathbf{lp}}>0$.
pi${p}_{i}$, the probability of the required beta distribution as defined by tail with pi = p(j)${p}_{i}={\mathbf{p}}\left(j\right)$, j = ((i1)  mod  lp) + 1.
Constraint: 0.0p(j)1.0$0.0\le {\mathbf{p}}\left(\mathit{j}\right)\le 1.0$, for j = 1,2,,lp$\mathit{j}=1,2,\dots ,{\mathbf{lp}}$.
3:     a(la) – double array
la, the dimension of the array, must satisfy the constraint la > 0${\mathbf{la}}>0$.
ai${a}_{i}$, the first parameter of the required beta distribution with ai = a(j)${a}_{i}={\mathbf{a}}\left(j\right)$, j = ((i1)  mod  la) + 1.
Constraint: 0.0 < a(j)106$0.0<{\mathbf{a}}\left(\mathit{j}\right)\le {10}^{6}$, 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$.
bi${b}_{i}$, the second parameter of the required beta distribution with bi = b(j)${b}_{i}={\mathbf{b}}\left(j\right)$, j = ((i1)  mod  lb) + 1.
Constraint: 0.0 < b(j)106$0.0<{\mathbf{b}}\left(\mathit{j}\right)\le {10}^{6}$, 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:     lp – int64int32nag_int scalar
Default: The dimension of the array p.
The length of the array p.
Constraint: lp > 0${\mathbf{lp}}>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$.
5:     tol – double scalar
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$1.0$ or less than 10 × machine precision (see nag_machine_precision (x02aj)), then the value of 10 × machine precision is used instead.
Default: 0.0$0.0$

None.

### Output Parameters

1:     beta( : $:$) – double array
Note: the dimension of the array beta must be at least max (ltail,lp,la,lb)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{ltail}},{\mathbf{lp}},{\mathbf{la}},{\mathbf{lb}}\right)$.
βpi${\beta }_{{p}_{i}}$, the deviates for the beta distribution.
2:     ivalid( : $:$) – int64int32nag_int array
Note: the dimension of the array ivalid must be at least max (ltail,lp,la,lb)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{ltail}},{\mathbf{lp}},{\mathbf{la}},{\mathbf{lb}}\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${\beta }_{{p}_{i}}$.
ivalid(i) = 2${\mathbf{ivalid}}\left(i\right)=2$
 On entry, pi < 0.0${p}_{i}<0.0$, or pi > 1.0${p}_{i}>1.0$.
ivalid(i) = 3${\mathbf{ivalid}}\left(i\right)=3$
 On entry, ai ≤ 0.0${a}_{i}\le 0.0$, or ai > 106${a}_{i}>{10}^{6}$, or bi ≤ 0.0${b}_{i}\le 0.0$, or bi > 106${b}_{i}>{10}^{6}$.
ivalid(i) = 4${\mathbf{ivalid}}\left(i\right)=4$
The solution has not converged but the result should be a reasonable approximation to the solution.
ivalid(i) = 5${\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:     ifail – int64int32nag_int scalar
${\mathrm{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 ifail = 1${\mathbf{ifail}}=1$
On entry, at least one value of tail, p, a, or b was invalid, or the solution failed to converge.
ifail = 2${\mathbf{ifail}}=2$
Constraint: ltail > 0${\mathbf{ltail}}>0$.
ifail = 3${\mathbf{ifail}}=3$
Constraint: lp > 0${\mathbf{lp}}>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 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 parameter values. See nag_stat_prob_beta_vector (g01se) for further comments on timings.

## Example

```function nag_stat_inv_cdf_beta_vector_example
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] = nag_stat_inv_cdf_beta_vector(tail, p, a, b);

fprintf('\n  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('%5c%9.4f%10.3f%10.3f%10.4f%8d\n', cell2mat(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
```
```

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

```
```function g01te_example
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('\n  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('%5c%9.4f%10.3f%10.3f%10.4f%8d\n', cell2mat(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
```
```

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

```