IBETA

The IBETA function computes the incomplete beta function.

This routine is written in the IDL language. Its source code can be found in the file ibeta.pro in the lib subdirectory of the IDL distribution.

Examples

For more information on using IBETA, see Additional Examples.

Example 1

Compute the incomplete beta function for the corresponding elements of A, B, and Z.

; Define an array of parametric exponents:

A = [0.5, 0.5, 1.0, 5.0, 10.0, 20.0]

B = [0.5, 0.5, 0.5, 5.0, 5.0, 10.0]

; Define the upper limits of integration:

Z = [0.01, 0.1, 0.1, 0.5, 1.0, 0.8]

; Compute the incomplete beta functions:

result = IBETA(A, B, Z)

PRINT, result

IDL prints:

[0.0637686, 0.204833, 0.0513167, 0.500000, 1.00000, 0.950736]

Syntax

Result = IBETA( A, B, Z [, /DOUBLE] [, EPS=value] [, ITER=variable] [, ITMAX=value] )

Return Value

If all arguments are scalar, the function returns a scalar. If all arguments are arrays, the function matches up the corresponding elements of A, B, and Z, returning an array with the same dimensions as the smallest array. If one argument is a scalar and the other arguments are arrays, the function uses the scalar value with each element of the arrays, and returns an array with the same dimensions as the smallest input array.

If any of the arguments are double-precision or if the DOUBLE keyword is set, the result is double-precision, otherwise the result is single-precision.

Arguments

A

A scalar or array that specifies the parametric exponent of the integrand. A may be complex.

B

A scalar or array that specifies the parametric exponent of the integrand. B may be complex.

Z

A scalar or array, in the interval [0, 1], that specifies the upper limit of integration. Z may be complex. If Z is not complex then the values must be in the range [0, 1].

Keywords

DOUBLE

Set this keyword to force the computation to be done in double precision.

EPS

Set this keyword to the desired relative accuracy, or tolerance. The default tolerance is 3.0e-7 for single precision, and 3.0d-12 for double precision.

ITER

Set this keyword to a named variable that will contain the actual number of iterations performed.

ITMAX

Set this keyword to specify the maximum number of iterations. The default value is 100.

Thread Pool Keywords

This routine is written to make use of IDL’s thread pool, which can increase execution speed on systems with multiple CPUs. The values stored in the !CPU system variable control whether IDL uses the thread pool for a given computation. In addition, you can use the thread pool keywords TPOOL_MAX_ELTS, TPOOL_MIN_ELTS, and TPOOL_NOTHREAD to override the defaults established by !CPU for a single invocation of this routine. See Thread Pool Keywords for details.

Additional Examples

Example 2

This example shows the difference in accuracy between the incomplete beta function computed with a low tolerance and the incomplete beta function computed with a high tolerance. The resulting surfaces show the relative errors of each. The relative error of the low tolerance ranges from 0 to 0.002 percent. The relative error of the high tolerance ranges from 0 to 0.0000000004 percent.

The code for this example is included in the file ibeta_ex2_doc.pro in the examples/doc/language subdirectory of the IDL distribution. Run this example procedure by entering ibeta_ex2_doc at the IDL command prompt or view the file in an IDL Editor window by entering .EDIT ibeta_ex2_doc.pro.

PRO ibeta_ex2_doc

; Define an array of parametric exponents.

parameterA = (DINDGEN(101)/100. + 1.D) # REPLICATE(1.D, 101)

parameterB = REPLICATE(1.D, 101) # (DINDGEN(101)/10. + 1.D)

; Define the upper limits of integration.

upperLimits = REPLICATE(0.1D, 101, 101)

; Compute the incomplete beta functions.

betaFunctions = IBETA(parameterA, parameterB, upperLimits)

; Compute the incomplete beta functions with a less

; accurate tolerance set.

laBetaFunctions = IBETA(parameterA, parameterB, $

upperLimits, EPS = 3.0e-4)

; Compute relative error.

relativeError = 100.* $

ABS((betaFunctions - laBetaFunctions)/betaFunctions)

; Display resulting relative error.

ISURFACE, relativeError, parameterA, parameterB, $

TITLE = 'Relative Error', STYLE=1,$

XTITLE = 'Parameter A', YTITLE = 'Parameter B', $

ZTITLE = 'Percent Error (%)',$

VIEW_TITLE='Compare IBETA with less accurate EPS', $

VIEW_GRID=[2,1], DIMENSIONS=[1000,500]

; Compute the incomplete beta functions with a more

; accurate tolerance set.

maBetaFunctions = IBETA(parameterA, parameterB, $

upperLimits, EPS = 3.0e-10)

; Compute relative error.

relativeError = 100.* $

ABS((maBetaFunctions - betaFunctions)/maBetaFunctions)

; Display resulting relative error.

ISURFACE, relativeError, parameterA, parameterB, $

TITLE = 'Relative Error', STYLE=1, $

XTITLE = 'Parameter A', YTITLE = 'Parameter B', $

ZTITLE = 'Percent Error (%)', $

VIEW_TITLE='Compare IBETA with more accurate EPS', /VIEW_NEXT

; Enlarge the text

ISETPROPERTY, 'text*', FONT_SIZE=36

ISETPROPERTY, 'axis*', FONT_SIZE=24

END

Version History

4.0	Introduced
5.6	A, B, and Z arguments accept complex input