g01 Chapter Contents
g01 Chapter Introduction
NAG C Library Manual

# NAG Library Function Documentnag_deviates_beta (g01fec)

## 1  Purpose

nag_deviates_beta (g01fec) returns the deviate associated with the given lower tail probability of the beta distribution.

## 2  Specification

 #include #include
 double nag_deviates_beta (double p, double a, double b, double tol, NagError *fail)

## 3  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)$.

## 4  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

## 5  Arguments

1:     pdoubleInput
On entry: $p$, the lower tail probability from the required beta distribution.
Constraint: $0.0\le {\mathbf{p}}\le 1.0$.
On entry: $a$, the first parameter of the required beta distribution.
Constraint: $0.0<{\mathbf{a}}\le {10}^{6}$.
3:     bdoubleInput
On entry: $b$, the second parameter of the required beta distribution.
Constraint: $0.0<{\mathbf{b}}\le {10}^{6}$.
4:     toldoubleInput
On entry: the relative accuracy required by you in the result. If nag_deviates_beta (g01fec) 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.
5:     failNagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

## 6  Error Indicators and Warnings

On any of the error conditions listed below except NE_RES_NOT_ACC and NE_SOL_NOT_CONV nag_deviates_beta (g01fec) returns $0.0$.
NE_ALLOC_FAIL
Dynamic memory allocation failed.
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.
NE_REAL_ARG_GT
On entry, ${\mathbf{a}}=〈\mathit{\text{value}}〉$ and ${\mathbf{b}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{a}}\le {10}^{6}$.
On entry, ${\mathbf{a}}=〈\mathit{\text{value}}〉$ and ${\mathbf{b}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{b}}\le {10}^{6}$.
On entry, ${\mathbf{p}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{p}}\le 1.0$.
NE_REAL_ARG_LE
On entry, ${\mathbf{a}}=〈\mathit{\text{value}}〉$ and ${\mathbf{b}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{a}}>0.0$.
On entry, ${\mathbf{a}}=〈\mathit{\text{value}}〉$ and ${\mathbf{b}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{b}}>0.0$.
NE_REAL_ARG_LT
On entry, ${\mathbf{p}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{p}}\ge 0.0$.
NE_RES_NOT_ACC
The requested accuracy has not been achieved. Use a larger value of tol. 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 Section 8). The result should be a reasonable approximation of the solution.
NE_SOL_NOT_CONV
The solution has failed to converge. However, the result should be a reasonable approximation. Requested accuracy not achieved when calculating beta probability. You should try setting tol larger.

## 7  Accuracy

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

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

## 9  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.

### 9.1  Program Text

Program Text (g01fece.c)

### 9.2  Program Data

Program Data (g01fece.d)

### 9.3  Program Results

Program Results (g01fece.r)