nag_deviates_beta_vector (g01tec) (PDF version)
g01 Chapter Contents
g01 Chapter Introduction
NAG Library Manual

# NAG Library Function Documentnag_deviates_beta_vector (g01tec)

## 1  Purpose

nag_deviates_beta_vector (g01tec) returns a number of deviates associated with given probabilities of the beta distribution.

## 2  Specification

 #include #include
 void nag_deviates_beta_vector (Integer ltail, const Nag_TailProbability tail[], Integer lp, const double p[], Integer la, const double a[], Integer lb, const double b[], double tol, double beta[], Integer ivalid[], NagError *fail)

## 3  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 Section 2.6 in the g01 Chapter Introduction for further information.
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

## 5  Arguments

1:     ltailIntegerInput
On entry: the length of the array tail.
Constraint: ${\mathbf{ltail}}>0$.
2:     tail[ltail]const Nag_TailProbabilityInput
On entry: 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]=\mathrm{Nag_LowerTail}$
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]=\mathrm{Nag_UpperTail}$
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}-1\right]=\mathrm{Nag_LowerTail}$ or $\mathrm{Nag_UpperTail}$, for $\mathit{j}=1,2,\dots ,{\mathbf{ltail}}$.
3:     lpIntegerInput
On entry: the length of the array p.
Constraint: ${\mathbf{lp}}>0$.
4:     p[lp]const doubleInput
On entry: ${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}-1\right]\le 1.0$, for $\mathit{j}=1,2,\dots ,{\mathbf{lp}}$.
5:     laIntegerInput
On entry: the length of the array a.
Constraint: ${\mathbf{la}}>0$.
6:     a[la]const doubleInput
On entry: ${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}-1\right]\le {10}^{6}$, for $\mathit{j}=1,2,\dots ,{\mathbf{la}}$.
7:     lbIntegerInput
On entry: the length of the array b.
Constraint: ${\mathbf{lb}}>0$.
8:     b[lb]const doubleInput
On entry: ${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}-1\right]\le {10}^{6}$, for $\mathit{j}=1,2,\dots ,{\mathbf{lb}}$.
9:     toldoubleInput
On entry: the relative accuracy required by you in the results. If nag_deviates_beta_vector (g01tec) is entered with tol greater than or equal to $1.0$ or less than  (see nag_machine_precision (X02AJC)), then the value of  is used instead.
10:   beta[$\mathit{dim}$]doubleOutput
Note: the dimension, dim, of the array beta must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{ltail}},{\mathbf{lp}},{\mathbf{la}},{\mathbf{lb}}\right)$.
On exit: ${\beta }_{{p}_{i}}$, the deviates for the beta distribution.
11:   ivalid[$\mathit{dim}$]IntegerOutput
Note: the dimension, dim, of the array ivalid must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{ltail}},{\mathbf{lp}},{\mathbf{la}},{\mathbf{lb}}\right)$.
On exit: ${\mathbf{ivalid}}\left[i-1\right]$ indicates any errors with the input arguments, with
${\mathbf{ivalid}}\left[i-1\right]=0$
No error.
${\mathbf{ivalid}}\left[i-1\right]=1$
 On entry, invalid value supplied in tail when calculating ${\beta }_{{p}_{i}}$.
${\mathbf{ivalid}}\left[i-1\right]=2$
 On entry, ${p}_{i}<0.0$, or ${p}_{i}>1.0$.
${\mathbf{ivalid}}\left[i-1\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-1\right]=4$
The solution has not converged but the result should be a reasonable approximation to the solution.
${\mathbf{ivalid}}\left[i-1\right]=5$
Requested accuracy not achieved when calculating the beta probability. The result should be a reasonable approximation to the correct solution.
12:   failNagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

## 6  Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
NE_ARRAY_SIZE
On entry, $\text{array size}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{la}}>0$.
On entry, $\text{array size}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{lb}}>0$.
On entry, $\text{array size}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{lp}}>0$.
On entry, $\text{array size}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{ltail}}>0$.
NE_BAD_PARAM
On entry, argument $⟨\mathit{\text{value}}⟩$ had an illegal value.
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
NW_IVALID
On entry, at least one value of tail, p, a, or b was invalid, or the solution failed to converge.
Check ivalid for more information.

## 7  Accuracy

The required precision, given by tol, should be achieved in most circumstances.

Not applicable.

## 9  Further Comments

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

## 10  Example

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

### 10.1  Program Text

Program Text (g01tece.c)

### 10.2  Program Data

Program Data (g01tece.d)

### 10.3  Program Results

Program Results (g01tece.r)

nag_deviates_beta_vector (g01tec) (PDF version)
g01 Chapter Contents
g01 Chapter Introduction
NAG Library Manual