# NAG FL Interfaces14ccf (beta_​incomplete)

## ▸▿ Contents

Settings help

FL Name Style:

FL Specification Language:

## 1Purpose

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

## 2Specification

Fortran Interface
 Subroutine s14ccf ( a, b, x, w, w1,
 Integer, Intent (Inout) :: ifail Real (Kind=nag_wp), Intent (In) :: a, b, x Real (Kind=nag_wp), Intent (Out) :: w, w1
#include <nag.h>
 void s14ccf_ (const double *a, const double *b, const double *x, double *w, double *w1, Integer *ifail)
The routine may be called by the names s14ccf or nagf_specfun_beta_incomplete.

## 3Description

s14ccf evaluates the regularized incomplete beta function and its complement in the normalized form
 $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
• $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.
s14ccf is derived from BRATIO in DiDonato and Morris (1992).

## 4References

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

## 5Arguments

1: $\mathbf{a}$Real (Kind=nag_wp) Input
On entry: the argument $a$ of the function.
Constraint: ${\mathbf{a}}\ge 0.0$.
2: $\mathbf{b}$Real (Kind=nag_wp) Input
On entry: 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: $\mathbf{x}$Real (Kind=nag_wp) Input
On entry: $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$.
4: $\mathbf{w}$Real (Kind=nag_wp) Output
On exit: the value of the incomplete beta function ${I}_{x}\left(a,b\right)$ evaluated from zero to $x$.
5: $\mathbf{w1}$Real (Kind=nag_wp) Output
On exit: 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.
6: $\mathbf{ifail}$Integer Input/Output
On entry: ifail must be set to $0$, $-1$ or $1$ to set behaviour on detection of an error; these values have no effect when no error is detected.
A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $-1$ means that an error message is printed while a value of $1$ means that it is not.
If halting is not appropriate, the value $-1$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $0$ is recommended. When the value $-\mathbf{1}$ or $\mathbf{1}$ is used it is essential to test the value of ifail on exit.
On exit: ${\mathbf{ifail}}={\mathbf{0}}$ unless the routine detects an error or a warning has been flagged (see Section 6).

## 6Error Indicators and Warnings

If on entry ${\mathbf{ifail}}=0$ or $-1$, explanatory error messages are output on the current error message unit (as defined by x04aaf).
Errors or warnings detected by the routine:
${\mathbf{ifail}}=1$
On entry, ${\mathbf{a}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{a}}\ge 0.0$.
On entry, ${\mathbf{b}}=⟨\mathit{\text{value}}⟩$.
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$
On entry, ${\mathbf{x}}=⟨\mathit{\text{value}}⟩$.
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$
See Section 7 in the Introduction to the NAG Library FL Interface for further information.
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library FL Interface for further information.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

## 7Accuracy

s14ccf 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.

## 8Parallelism and Performance

s14ccf is not threaded in any implementation.

None.

## 10Example

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.

### 10.1Program Text

Program Text (s14ccfe.f90)

### 10.2Program Data

Program Data (s14ccfe.d)

### 10.3Program Results

Program Results (s14ccfe.r)