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_beta_vector (g01se)

## Purpose

nag_stat_prob_beta_vector (g01se) computes a number of lower or upper tail probabilities for the beta distribution.

## Syntax

[p, ivalid, ifail] = g01se(tail, beta, a, b, 'ltail', ltail, 'lbeta', lbeta, 'la', la, 'lb', lb)
[p, ivalid, ifail] = nag_stat_prob_beta_vector(tail, beta, a, b, 'ltail', ltail, 'lbeta', lbeta, 'la', la, 'lb', lb)

## Description

The lower tail probability, $P\left({B}_{i}\le {\beta }_{i}:{a}_{i},{b}_{i}\right)$ is defined by
 $P Bi ≤ βi :ai,bi = Γ ai + bi Γ ai Γ bi ∫ 0 βi Bi ai-1 1-Bi bi-1 dBi = Iβi ai,bi , 0 ≤ βi ≤ 1 ; ai , bi > 0 .$
The function ${I}_{{\beta }_{i}}\left({a}_{i},{b}_{i}\right)$, also known as the incomplete beta function is calculated using nag_specfun_beta_incomplete (s14cc).
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

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Hastings N A J and Peacock J B (1975) Statistical Distributions Butterworth
Majumder K L and Bhattacharjee G P (1973) Algorithm AS 63. The incomplete beta integral Appl. Statist. 22 409–411

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{tail}\left({\mathbf{ltail}}\right)$ – cell array of strings
Indicates whether a lower or upper tail probabilities are required. For , for $\mathit{i}=1,2,\dots ,\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{ltail}},{\mathbf{lbeta}},{\mathbf{la}},{\mathbf{lb}}\right)$:
${\mathbf{tail}}\left(j\right)=\text{'L'}$
The lower tail probability is returned, i.e., ${p}_{i}=P\left({B}_{i}\le {\beta }_{i}:{a}_{i},{b}_{i}\right)$.
${\mathbf{tail}}\left(j\right)=\text{'U'}$
The upper tail probability is returned, i.e., ${p}_{i}=P\left({B}_{i}\ge {\beta }_{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{beta}\left({\mathbf{lbeta}}\right)$ – double array
${\beta }_{i}$, the value of the beta variate with ${\beta }_{i}={\mathbf{beta}}\left(j\right)$, .
Constraint: $0.0\le {\mathbf{beta}}\left(\mathit{j}\right)\le 1.0$, for $\mathit{j}=1,2,\dots ,{\mathbf{lbeta}}$.
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: ${\mathbf{a}}\left(\mathit{j}\right)>0.0$, 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: ${\mathbf{b}}\left(\mathit{j}\right)>0.0$, 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{lbeta}$int64int32nag_int scalar
Default: the dimension of the array beta.
The length of the array beta.
Constraint: ${\mathbf{lbeta}}>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$.

### Output Parameters

1:     $\mathrm{p}\left(:\right)$ – double array
The dimension of the array p will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{ltail}},{\mathbf{lbeta}},{\mathbf{la}},{\mathbf{lb}}\right)$
${p}_{i}$, the probabilities 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{lbeta}},{\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 ${p}_{i}$.
${\mathbf{ivalid}}\left(i\right)=2$
 On entry, ${\beta }_{i}<0.0$, or ${\beta }_{i}>1.0$.
${\mathbf{ivalid}}\left(i\right)=3$
 On entry, ${a}_{i}\le 0.0$, or ${b}_{i}\le 0.0$,
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_prob_beta_vector (g01se) 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 beta, a, b or tail was invalid.
${\mathbf{ifail}}=2$
Constraint: ${\mathbf{ltail}}>0$.
${\mathbf{ifail}}=3$
Constraint: ${\mathbf{lbeta}}>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 accuracy is limited by the error in the incomplete beta function. See Accuracy in nag_specfun_beta_incomplete (s14cc) for further details.

None.

## Example

This example reads values from a number of beta distributions and computes the associated lower tail probabilities.
```function g01se_example

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

tail = {'L'; 'L'; 'L'};
x = [0.25; 0.75; 0.5];
a = [1.0;  1.5;  2.0];
b = [2.0;  1.5;  1.0];
% calculate probability
[p, ivalid, ifail] = g01se( ...
tail, x, a, b);

fprintf('   x       a       b       p\n');
lx    = numel(x);
la    = numel(a);
lb    = numel(b);
ltail = numel(tail);
len   = max ([lx, la, lb, ltail]);
for i=0:len-1
fprintf('%6.4f%8.4f%8.4f%8.4f\n', x(mod(i,lx)+1), a(mod(i,la)+1), ...
b(mod(i,lb)+1), p(i+1));
end

```
```g01se example results

x       a       b       p
0.2500  1.0000  2.0000  0.4375
0.7500  1.5000  1.5000  0.8045
0.5000  2.0000  1.0000  0.2500
```