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_specfun_beta_incomplete (s14cc)

## Purpose

nag_specfun_beta_incomplete (s14cc) computes values for the incomplete beta function ${I}_{x}\left(a,b\right)$ and its complement $1-{I}_{x}\left(a,b\right)$.

## Syntax

[w, w1, ifail] = s14cc(a, b, x)
[w, w1, ifail] = nag_specfun_beta_incomplete(a, b, x)

## Description

nag_specfun_beta_incomplete (s14cc) evaluates the incomplete beta function and its complement in the normalized form
 $Ixa,b = 1 Ba,b ∫ 0 x ta-1 1-t b-1 dt 1–Ix a,b = Iy b,a , where ​ y=1-x ,$
with
• $0\le x\le 1$,
• $a\ge 0$ and $b\ge 0$,
• and the beta function $B\left(a,b\right)$ is defined as $B\left(a,b\right)=\underset{0}{\overset{1}{\int }}{t}^{a-1}{\left(1-t\right)}^{b-1}dt=\frac{\Gamma \left(a\right)\Gamma \left(b\right)}{\Gamma \left(a+b\right)}$ where $\Gamma \left(y\right)$ is the gamma function.
Several methods are used to evaluate the functions depending on the arguments $a$, $b$ and $x$. The methods include Wise's asymptotic expansion (see Wise (1950)) when $a>b$, continued fraction derived by DiDonato and Morris (1992) when $a$, $b>1$, and power series when $b\le 1$ or $b×x\le 0.7$. When both $a$ and $b$ are large, specifically $a$, $b\ge 15$, the DiDonato and Morris (1992) asymptotic expansion is employed for greater efficiency.
Once either ${I}_{x}\left(a,b\right)$ or ${I}_{y}\left(b,a\right)$ is computed, the other is obtained by subtraction from $1$. In order to avoid loss of relative precision in this subtraction, the smaller of ${I}_{x}\left(a,b\right)$ and ${I}_{y}\left(b,a\right)$ is computed first.
nag_specfun_beta_incomplete (s14cc) is derived from BRATIO in DiDonato and Morris (1992).

## References

DiDonato A R and Morris A H (1992) Algorithm 708: Significant digit computation of the incomplete beta function ratios ACM Trans. Math. Software 18 360–373
Wise M E (1950) The incomplete beta function as a contour integral and a quickly converging series for its inverse Biometrika 37 208–218

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{a}$ – double scalar
The argument $a$ of the function.
Constraint: ${\mathbf{a}}\ge 0.0$.
2:     $\mathrm{b}$ – double scalar
The argument $b$ of the function.
Constraints:
• ${\mathbf{b}}\ge 0.0$;
• either ${\mathbf{b}}\ne 0.0$ or ${\mathbf{a}}\ne 0.0$.
3:     $\mathrm{x}$ – double scalar
$x$, upper limit of integration.
Constraints:
• $0.0\le {\mathbf{x}}\le 1.0$;
• either ${\mathbf{x}}\ne 0.0$ or ${\mathbf{a}}\ne 0.0$;
• either $1-{\mathbf{x}}\ne 0.0$ or ${\mathbf{b}}\ne 0.0$.

None.

### Output Parameters

1:     $\mathrm{w}$ – double scalar
The value of the incomplete beta function ${I}_{x}\left(a,b\right)$ evaluated from zero to $x$.
2:     $\mathrm{w1}$ – double scalar
The value of the complement of the incomplete beta function $1-{I}_{x}\left(a,b\right)$, i.e., the incomplete beta function evaluated from $x$ to one.
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

Errors or warnings detected by the function:
${\mathbf{ifail}}=1$
Constraint: ${\mathbf{a}}\ge 0.0$.
Constraint: ${\mathbf{b}}\ge 0.0$.
${\mathbf{ifail}}=2$
On entry, a and b were zero.
Constraint: a or b must be nonzero.
${\mathbf{ifail}}=3$
Constraint: $0.0\le {\mathbf{x}}\le 1.0$.
${\mathbf{ifail}}=4$
On entry, x and a were zero.
Constraint: x or a must be nonzero.
${\mathbf{ifail}}=5$
On entry, $1.0-{\mathbf{x}}$ and b were zero.
Constraint: $1.0-{\mathbf{x}}$ or b must be nonzero.
${\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

nag_specfun_beta_incomplete (s14cc) is designed to maintain relative accuracy for all arguments. For very tiny results (of the order of machine precision or less) some relative accuracy may be lost – loss of three or four decimal places has been observed in experiments. For other arguments full relative accuracy may be expected.

None.

## Example

This example reads values of the arguments $a$ and $b$ from a file, evaluates the function and its complement for $10$ different values of $x$ and prints the results.
```function s14cc_example

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

a = 5.3;
b = 10.1;
fprintf('\n   a     b     x          Ix(a,b)          1-Ix(a,b)\n');
for x = 0.01:0.01:0.1
[w, w1, ifail] = s14cc(a, b, x);
fprintf('%6.2f%6.2f%6.2f%17.4e%17.4e\n', a, b, x, w, w1);
end

```
```s14cc example results

a     b     x          Ix(a,b)          1-Ix(a,b)
5.30 10.10  0.01       6.4755e-08       1.0000e+00
5.30 10.10  0.02       2.3613e-06       1.0000e+00
5.30 10.10  0.03       1.8734e-05       9.9998e-01
5.30 10.10  0.04       7.9575e-05       9.9992e-01
5.30 10.10  0.05       2.3997e-04       9.9976e-01
5.30 10.10  0.06       5.8255e-04       9.9942e-01
5.30 10.10  0.07       1.2174e-03       9.9878e-01
5.30 10.10  0.08       2.2797e-03       9.9772e-01
5.30 10.10  0.09       3.9249e-03       9.9608e-01
5.30 10.10  0.10       6.3236e-03       9.9368e-01
```