# NAG FL Interfaces14cqf (beta_​incomplete_​vector)

## ▸▿ Contents

Settings help

FL Name Style:

FL Specification Language:

## 1Purpose

s14cqf computes an array of 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 s14cqf ( n, a, b, x, w, w1,
 Integer, Intent (In) :: n Integer, Intent (Inout) :: ifail Integer, Intent (Out) :: ivalid(n) Real (Kind=nag_wp), Intent (In) :: a(n), b(n), x(n) Real (Kind=nag_wp), Intent (Out) :: w(n), w1(n)
#include <nag.h>
 void s14cqf_ (const Integer *n, const double a[], const double b[], const double x[], double w[], double w1[], Integer ivalid[], Integer *ifail)
The routine may be called by the names s14cqf or nagf_specfun_beta_incomplete_vector.

## 3Description

s14cqf evaluates the regularized incomplete beta function ${I}_{x}\left(a,b\right)$ and its complement $1–{I}_{x}\left(a,b\right)$ in the normalized form, for arrays of arguments ${x}_{i}$, ${a}_{i}$ and ${b}_{i}$, for $\mathit{i}=1,2,\dots ,n$. The incomplete beta function and its complement are given by
 $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.
s14cqf 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{n}$Integer Input
On entry: $n$, the number of points.
Constraint: ${\mathbf{n}}\ge 0$.
2: $\mathbf{a}\left({\mathbf{n}}\right)$Real (Kind=nag_wp) array Input
On entry: the argument ${a}_{\mathit{i}}$ of the function, for $\mathit{i}=1,2,\dots ,{\mathbf{n}}$.
Constraint: ${\mathbf{a}}\left(\mathit{i}\right)\ge 0.0$, for $\mathit{i}=1,2,\dots ,{\mathbf{n}}$.
3: $\mathbf{b}\left({\mathbf{n}}\right)$Real (Kind=nag_wp) array Input
On entry: the argument ${b}_{\mathit{i}}$ of the function, for $\mathit{i}=1,2,\dots ,{\mathbf{n}}$.
Constraints:
• ${\mathbf{b}}\left(\mathit{i}\right)\ge 0.0$, for $\mathit{i}=1,2,\dots ,{\mathbf{n}}$;
• ${\mathbf{b}}\left(\mathit{i}\right)\ne 0.0$ or ${\mathbf{a}}\left(\mathit{i}\right)\ne 0.0$, for $\mathit{i}=1,2,\dots ,{\mathbf{n}}$.
4: $\mathbf{x}\left({\mathbf{n}}\right)$Real (Kind=nag_wp) array Input
On entry: ${x}_{\mathit{i}}$, the upper limit of integration, for $\mathit{i}=1,2,\dots ,{\mathbf{n}}$.
Constraints:
• ${\mathbf{x}}\left(\mathit{i}\right)\ge 0.0$, for $\mathit{i}=1,2,\dots ,{\mathbf{n}}$;
• ${\mathbf{x}}\left(\mathit{i}\right)\ne 0.0$ or ${\mathbf{a}}\left(\mathit{i}\right)\ne 0.0$, for $\mathit{i}=1,2,\dots ,{\mathbf{n}}$;
• $1-{\mathbf{x}}\left(\mathit{i}\right)\ne 0.0$ or ${\mathbf{b}}\left(\mathit{i}\right)\ne 0.0$, for $\mathit{i}=1,2,\dots ,{\mathbf{n}}$.
5: $\mathbf{w}\left({\mathbf{n}}\right)$Real (Kind=nag_wp) array Output
On exit: the values of the incomplete beta function ${I}_{{x}_{i}}\left({a}_{i},{b}_{i}\right)$ evaluated from zero to ${x}_{i}$.
6: $\mathbf{w1}\left({\mathbf{n}}\right)$Real (Kind=nag_wp) array Output
On exit: the values of the complement of the incomplete beta function $1-{I}_{{x}_{i}}\left({a}_{i},{b}_{i}\right)$, i.e., the incomplete beta function evaluated from ${x}_{i}$ to one.
7: $\mathbf{ivalid}\left({\mathbf{n}}\right)$Integer array Output
On exit: ${\mathbf{ivalid}}\left(\mathit{i}\right)$ contains the error code for the $\mathit{i}$th evaluation, for $\mathit{i}=1,2,\dots ,{\mathbf{n}}$.
${\mathbf{ivalid}}\left(i\right)=0$
No error.
${\mathbf{ivalid}}\left(i\right)=1$
${a}_{i}\text{​ or ​}{b}_{i}<0$.
${\mathbf{ivalid}}\left(i\right)=2$
Both ${a}_{i}\text{​ and ​}{b}_{i}=0$.
${\mathbf{ivalid}}\left(i\right)=3$
${x}_{i}\notin \left[0,1\right]$.
${\mathbf{ivalid}}\left(i\right)=4$
Both ${x}_{i}\text{​ and ​}{a}_{i}=0$.
${\mathbf{ivalid}}\left(i\right)=5$
Both $1-{x}_{i}\text{​ and ​}{b}_{i}=0$.
8: $\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, at least one argument had an invalid value.
${\mathbf{ifail}}=2$
On entry, ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{n}}\ge 0$.
${\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

s14cqf 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

s14cqf is not threaded in any implementation.

None.

## 10Example

This example reads $10$ values for each vector argument $a$, $b$ and $x$ from a file. It then evaluates the function and its complement for each set of values.

### 10.1Program Text

Program Text (s14cqfe.f90)

### 10.2Program Data

Program Data (s14cqfe.d)

### 10.3Program Results

Program Results (s14cqfe.r)