NAG Library Function Document

nag_deviates_beta_vector (g01tec)

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,

β_{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 (B_{i} \leq β_{p_{i}} : a_{i}, b_{i}) = p_{i} = \frac{Γ (a_{i} + b_{i})}{Γ (a_{i}) Γ (b_{i})} \int_{0}^{β_{p_{i}}} {B_{i}}^{a_{i} - 1} {(1 - B_{i})}^{b_{i} - 1} d B_{i}, 0 \leq β_{p_{i}} \leq 1; ​ a_{i}, b_{i} > 0 .

The algorithm is a modified version of the Newton–Raphson method, following closely that of Cran et al. (1977).

An initial approximation,

β_{i 0}

, to

β_{p_{i}}

is found (see Cran et al. (1977)), and the Newton–Raphson iteration

β_{k} = β_{k - 1} - \frac{f_{i} (β_{k - 1})}{{f_{i}}^{'} (β_{k - 1})},

where

f_{i} (β_{k}) = P (B_{i} \leq β_{k} : a_{i}, b_{i}) - p_{i}

is used, with modifications to ensure that

β_{k}

remains in the range

(0, 1)

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.

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: ltail – IntegerInput

On entry: the length of the array tail.

Constraint:

ltail > 0

2: tail[ltail] – const Nag_TailProbabilityInput

On entry: indicates which tail the supplied probabilities represent. For

j = (i - 1) mod ltail

, for

i = 1, 2, \dots, \max (ltail, lp, la, lb)

$tail [j] = Nag_LowerTail$: The lower tail probability, i.e., $p_{i} = P (B_{i} \leq β_{p_{i}} : a_{i}, b_{i})$ .
$tail [j] = Nag_UpperTail$: The upper tail probability, i.e., $p_{i} = P (B_{i} \geq β_{p_{i}} : a_{i}, b_{i})$ .

Constraint:

tail [j - 1] = Nag_LowerTail

Nag_UpperTail

, for

j = 1, 2, \dots, ltail

3: lp – IntegerInput

On entry: the length of the array p.

Constraint:

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} = p [j]

j = (i - 1) mod lp

Constraint:

0.0 \leq p [j - 1] \leq 1.0

, for

j = 1, 2, \dots, lp

5: la – IntegerInput

On entry: the length of the array a.

Constraint:

la > 0

6: a[la] – const doubleInput

On entry:

a_{i}

, the first parameter of the required beta distribution with

a_{i} = a [j]

j = (i - 1) mod la

Constraint:

0.0 < a [j - 1] \leq 10^{6}

, for

j = 1, 2, \dots, la

7: lb – IntegerInput

On entry: the length of the array b.

Constraint:

lb > 0

8: b[lb] – const doubleInput

On entry:

b_{i}

, the second parameter of the required beta distribution with

b_{i} = b [j]

j = (i - 1) mod lb

Constraint:

0.0 < b [j - 1] \leq 10^{6}

, for

j = 1, 2, \dots, lb

9: tol – doubleInput

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

10 \times machine precision

(see nag_machine_precision (X02AJC)), then the value of

10 \times machine precision

is used instead.

10: beta[ $\dim$ ] – doubleOutput

Note: the dimension, dim, of the array beta must be at least

\max (ltail, lp, la, lb)

On exit:

β_{p_{i}}

, the deviates for the beta distribution.

11: ivalid[ $\dim$ ] – IntegerOutput

Note: the dimension, dim, of the array ivalid must be at least

\max (ltail, lp, la, lb)

On exit:

ivalid [i - 1]

indicates any errors with the input arguments, with

$ivalid [i - 1] = 0$

No error.

$ivalid [i - 1] = 1$

On entry,

invalid value supplied in tail when calculating

β_{p_{i}}

$ivalid [i - 1] = 2$

On entry,	$p_{i} < 0.0$ ,
or	$p_{i} > 1.0$ .

$ivalid [i - 1] = 3$

On entry,	$a_{i} \leq 0.0$ ,
or	$a_{i} > 10^{6}$ ,
or	$b_{i} \leq 0.0$ ,
or	$b_{i} > 10^{6}$ .

$ivalid [i - 1] = 4$

The solution has not converged but the result should be a reasonable approximation to the solution.

$ivalid [i - 1] = 5$

Requested accuracy not achieved when calculating the beta probability. The result should be a reasonable approximation to the correct solution.

12: fail – NagError *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, $array size = ⟨value⟩$ .
Constraint: $la > 0$ .
On entry, $array size = ⟨value⟩$ .
Constraint: $lb > 0$ .
On entry, $array size = ⟨value⟩$ .
Constraint: $lp > 0$ .
On entry, $array size = ⟨value⟩$ .
Constraint: $ltail > 0$ .
NE_BAD_PARAM: On entry, argument $⟨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.

8 Parallelism and Performance

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.

NAG Library Function Documentnag_deviates_beta_vector (g01tec)

+− Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results

NAG Library Function Document

nag_deviates_beta_vector (g01tec)