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

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.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private static final double
    Maximum allowed numerical error.
    private static final double[]
    The coefficients of the series expansion of the Δ function.
    private static final double
    The constant value of ½log 2π.
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    Default constructor.
  • Method Summary

    Modifier and Type
    Method
    Description
    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.
    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 Details

    • DEFAULT_EPSILON

      private static final double DEFAULT_EPSILON
      Maximum allowed numerical error.
      See Also:
    • HALF_LOG_TWO_PI

      private static final double HALF_LOG_TWO_PI
      The constant value of ½log 2π.
      See Also:
    • 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 Details

    • Beta

      private Beta()
      Default constructor. Prohibit instantiation.
  • Method Details

    • 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:
      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:
      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.