org.apache.commons.math3.special

## Class Beta

- java.lang.Object
- - org.apache.commons.math3.special.Beta

    public class Beta
    extends Object

This is a utility class that provides computation methods related to the Beta family of functions.

Implementation of `logBeta(double, double)` is based on the algorithms described in

- Didonato and Morris (1986), Computation of the Incomplete Gamma Function Ratios and their Inverse, TOMS 12(4), 377-393,
- Didonato and Morris (1992), Algorithm 708: Significant Digit Computation of the Incomplete Beta Function Ratios, TOMS 18(3), 360-373,

and implemented in the NSWC Library of Mathematical Functions, available here. This library is "approved for public release", and the Copyright guidance indicates that unless otherwise stated in the code, all FORTRAN functions in this library are license free. Since no such notice appears in the code these functions can safely be ported to Commons-Math.

Version:
  $Id: Beta.java 1420669 2012-12-12 13:40:35Z erans $

### Field Summary

Fields
`private static double` `DEFAULT_EPSILON` Maximum allowed numerical error.
`private static double[]` `DELTA` The coefficients of the series expansion of the Δ function.
`private static double` `HALF_LOG_TWO_PI` The constant value of ½log 2π.

### Constructor Summary

Constructors
`private` `Beta()` Default constructor.

### Method Summary

Methods
`private static double` `deltaMinusDeltaSum(double a, double b)` Returns the value of Δ(b) - Δ(a + b), with 0 ≤ a ≤ b and b ≥ 10.
`static double` `logBeta(double p, double q)` Returns the value of log B(p, q) for 0 ≤ x ≤ 1 and p, q > 0.
`static double` `logBeta(double a, double b, double epsilon, int maxIterations)` Deprecated. as of version 3.1, this method is deprecated as the computation of the beta function is no longer iterative; it will be removed in version 4.0. Current implementation of this method internally calls `logBeta(double, double)`.
`private static double` `logGammaMinusLogGammaSum(double a, double b)` Returns the value of log[Γ(b) / Γ(a + b)] for a ≥ 0 and b ≥ 10.
`private static double` `logGammaSum(double a, double b)` Returns the value of log Γ(a + b) for 1 ≤ a, b ≤ 2.
`static double` `regularizedBeta(double x, double a, double b)` Returns the regularized beta function I(x, a, b).
`static double` `regularizedBeta(double x, double a, double b, double epsilon)` Returns the regularized beta function I(x, a, b).
`static double` `regularizedBeta(double x, double a, double b, double epsilon, int maxIterations)` Returns the regularized beta function I(x, a, b).
`static double` `regularizedBeta(double x, double a, double b, int maxIterations)` Returns the regularized beta function I(x, a, b).
`private static double` `sumDeltaMinusDeltaSum(double p, double q)` Returns the value of Δ(p) + Δ(q) - Δ(p + q), with p, q ≥ 10.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Field Detail

#### DEFAULT_EPSILON

    private static final double DEFAULT_EPSILON

Maximum allowed numerical error.

See Also:
  Constant Field Values

#### HALF_LOG_TWO_PI

    private static final double HALF_LOG_TWO_PI

The constant value of ½log 2π.

See Also:
  Constant Field Values

#### DELTA

    private static final double[] DELTA

The coefficients of the series expansion of the Δ function. This function is defined as follows

Δ(x) = log Γ(x) - (x - 0.5) log a + a - 0.5 log 2π,

see equation (23) in Didonato and Morris (1992). The series expansion, which applies for x ≥ 10, reads

                     14
                    ====
                 1  \                2 n
         Δ(x) = ---  >    d  (10 / x)
                 x  /      n
                    ====
                    n = 0

### Constructor Detail

#### Beta

    private Beta()

Default constructor. Prohibit instantiation.

### Method Detail

#### regularizedBeta

    public static double regularizedBeta(double x,
                         double a,
                         double b)

Returns the regularized beta function I(x, a, b).

Parameters:
  `x` - Value.
  `a` - Parameter `a`.
  `b` - Parameter `b`.
Returns:
  the regularized beta function I(x, a, b).
Throws:
  `MaxCountExceededException` - if the algorithm fails to converge.

#### regularizedBeta

    public static double regularizedBeta(double x,
                         double a,
                         double b,
                         double epsilon)

Returns the regularized beta function I(x, a, b).

Parameters:
  `x` - Value.
  `a` - Parameter `a`.
  `b` - Parameter `b`.
  `epsilon` - When the absolute value of the nth item in the series is less than epsilon the approximation ceases to calculate further elements in the series.
Returns:
  the regularized beta function I(x, a, b)
Throws:
  `MaxCountExceededException` - if the algorithm fails to converge.

#### regularizedBeta

    public static double regularizedBeta(double x,
                         double a,
                         double b,
                         int maxIterations)

Returns the regularized beta function I(x, a, b).

Parameters:
  `x` - the value.
  `a` - Parameter `a`.
  `b` - Parameter `b`.
  `maxIterations` - Maximum number of "iterations" to complete.
Returns:
  the regularized beta function I(x, a, b)
Throws:
  `MaxCountExceededException` - if the algorithm fails to converge.

#### regularizedBeta

    public static double regularizedBeta(double x,
                         double a,
                         double b,
                         double epsilon,
                         int maxIterations)

Returns the regularized beta function I(x, a, b). The implementation of this method is based on:

- Regularized Beta Function.
- Regularized Beta Function.

Parameters:
  `x` - the value.
  `a` - Parameter `a`.
  `b` - Parameter `b`.
  `epsilon` - When the absolute value of the nth item in the series is less than epsilon the approximation ceases to calculate further elements in the series.
  `maxIterations` - Maximum number of "iterations" to complete.
Returns:
  the regularized beta function I(x, a, b)
Throws:
  `MaxCountExceededException` - if the algorithm fails to converge.

#### logBeta

    @Deprecated
    public static double logBeta(double a,
                            double b,
                            double epsilon,
                            int maxIterations)

Deprecated. as of version 3.1, this method is deprecated as the computation of the beta function is no longer iterative; it will be removed in version 4.0. Current implementation of this method internally calls `logBeta(double, double)`.
Returns the natural logarithm of the beta function B(a, b). The implementation of this method is based on:

- Beta Function, equation (1).

Parameters:
  `a` - Parameter `a`.
  `b` - Parameter `b`.
  `epsilon` - This parameter is ignored.
  `maxIterations` - This parameter is ignored.
Returns:
  log(B(a, b)).

#### logGammaSum

    private static double logGammaSum(double a,
                     double b)
                               throws OutOfRangeException

Returns the value of log Γ(a + b) for 1 ≤ a, b ≤ 2. Based on the NSWC Library of Mathematics Subroutines double precision implementation, `DGSMLN`. In `BetaTest#testLogGammaSum()`, this private method is accessed through reflection.

Parameters:
  `a` - First argument.
  `b` - Second argument.
Returns:
  the value of `log(Gamma(a + b))`.
Throws:
  `OutOfRangeException` - if `a` or `b` is lower than `1.0` or greater than `2.0`.

#### logGammaMinusLogGammaSum

    private static double logGammaMinusLogGammaSum(double a,
                                  double b)
                                            throws NumberIsTooSmallException

Returns the value of log[Γ(b) / Γ(a + b)] for a ≥ 0 and b ≥ 10. Based on the NSWC Library of Mathematics Subroutines double precision implementation, `DLGDIV`. In `BetaTest#testLogGammaMinusLogGammaSum()`, this private method is accessed through reflection.

Parameters:
  `a` - First argument.
  `b` - Second argument.
Returns:
  the value of `log(Gamma(b) / Gamma(a + b))`.
Throws:
  `NumberIsTooSmallException` - if `a < 0.0` or `b < 10.0`.

#### deltaMinusDeltaSum

    private static double deltaMinusDeltaSum(double a,
                            double b)
                                      throws OutOfRangeException,
                                             NumberIsTooSmallException

Returns the value of Δ(b) - Δ(a + b), with 0 ≤ a ≤ b and b ≥ 10. Based on equations (26), (27) and (28) in Didonato and Morris (1992).

Parameters:
  `a` - First argument.
  `b` - Second argument.
Returns:
  the value of `Delta(b) - Delta(a + b)`
Throws:
  `OutOfRangeException` - if `a < 0` or `a > b`
  `NumberIsTooSmallException` - if `b < 10`

#### sumDeltaMinusDeltaSum

    private static double sumDeltaMinusDeltaSum(double p,
                               double q)

Returns the value of Δ(p) + Δ(q) - Δ(p + q), with p, q ≥ 10. Based on the NSWC Library of Mathematics Subroutines double precision implementation, `DBCORR`. In `BetaTest#testSumDeltaMinusDeltaSum()`, this private method is accessed through reflection.

Parameters:
  `p` - First argument.
  `q` - Second argument.
Returns:
  the value of `Delta(p) + Delta(q) - Delta(p + q)`.
Throws:
  `NumberIsTooSmallException` - if `p < 10.0` or `q < 10.0`.

#### logBeta

    public static double logBeta(double p,
                 double q)

Returns the value of log B(p, q) for 0 ≤ x ≤ 1 and p, q > 0. Based on the NSWC Library of Mathematics Subroutines implementation, `DBETLN`.

Parameters:
  `p` - First argument.
  `q` - Second argument.
Returns:
  the value of `log(Beta(p, q))`, `NaN` if `p <= 0` or `q <= 0`.