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 Ix(a,b)${I}_{x}\left(a,b\right)$ and its complement 1Ix(a,b)$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
Ix(a,b) =
 x 1/(B(a,b)) ∫ ta − 1(1 − t)b − 1dt 0
1Ix (a,b) = Iy (b,a) , where ​ y = 1x ,
$Ix(a,b) = 1 B(a,b) ∫ 0 x ta-1 (1-t) b-1 dt 1–Ix (a,b) = Iy (b,a) , where ​ y=1-x ,$
with
• 0x1$0\le x\le 1$,
• a0$a\ge 0$ and b0$b\ge 0$,
• and the beta function B(a,b)$B\left(a,b\right)$ is defined as B(a,b) = 01 ta1 (1t)b1 dt = ( Γ(a) Γ(b) )/(Γ(a + b))$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 Γ(y)$\Gamma \left(y\right)$ is the gamma function.
Several methods are used to evaluate the functions depending on the arguments a$a$, b$b$ and x$x$. The methods include Wise's asymptotic expansion (see Wise (1950)) when a > b$a>b$, continued fraction derived by DiDonato and Morris (1992) when a$a$, b > 1$b>1$, and power series when b1$b\le 1$ or b × x0.7$b×x\le 0.7$. When both a$a$ and b$b$ are large, specifically a$a$, b15$b\ge 15$, the DiDonato and Morris (1992) asymptotic expansion is employed for greater efficiency.
Once either Ix(a,b)${I}_{x}\left(a,b\right)$ or Iy(b,a)${I}_{y}\left(b,a\right)$ is computed, the other is obtained by subtraction from 1$1$. In order to avoid loss of relative precision in this subtraction, the smaller of Ix(a,b)${I}_{x}\left(a,b\right)$ and Iy(b,a)${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:     a – double scalar
The argument a$a$ of the function.
Constraint: a0.0${\mathbf{a}}\ge 0.0$.
2:     b – double scalar
The argument b$b$ of the function.
Constraints:
• b0.0${\mathbf{b}}\ge 0.0$;
• either b0.0${\mathbf{b}}\ne 0.0$ or a0.0${\mathbf{a}}\ne 0.0$.
3:     x – double scalar
x$x$, upper limit of integration.
Constraints:
• 0.0x1.0$0.0\le {\mathbf{x}}\le 1.0$;
• either x0.0${\mathbf{x}}\ne 0.0$ or a0.0${\mathbf{a}}\ne 0.0$;
• either 1x0.0$1-{\mathbf{x}}\ne 0.0$ or b0.0${\mathbf{b}}\ne 0.0$.

None.

None.

### Output Parameters

1:     w – double scalar
The value of the incomplete beta function Ix(a,b)${I}_{x}\left(a,b\right)$ evaluated from zero to x$x$.
2:     w1 – double scalar
The value of the complement of the incomplete beta function 1Ix(a,b)$1-{I}_{x}\left(a,b\right)$, i.e., the incomplete beta function evaluated from x$x$ to one.
3:     ifail – int64int32nag_int scalar
${\mathrm{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:
ifail = 1${\mathbf{ifail}}=1$
Constraint: a0.0${\mathbf{a}}\ge 0.0$.
Constraint: b0.0${\mathbf{b}}\ge 0.0$.
ifail = 2${\mathbf{ifail}}=2$
On entry, a and b were zero.
Constraint: a or b must be nonzero.
ifail = 3${\mathbf{ifail}}=3$
Constraint: 0.0x1.0$0.0\le {\mathbf{x}}\le 1.0$.
ifail = 4${\mathbf{ifail}}=4$
On entry, x and a were zero.
Constraint: x or a must be nonzero.
ifail = 5${\mathbf{ifail}}=5$
On entry, 1.0x$1.0-{\mathbf{x}}$ and b were zero.
Constraint: 1.0x$1.0-{\mathbf{x}}$ or b must be nonzero.
ifail = 999${\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

```function nag_specfun_beta_incomplete_example
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] = nag_specfun_beta_incomplete(a, b, x);
fprintf('%6.2f%6.2f%6.2f%17.4e%17.4e\n', a, b, x, w, w1);
end
```
```

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

```
```function s14cc_example
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
```
```

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

```