cern.jet.stat

## Class Probability

- java.lang.Object
- - cern.jet.math.Constants
  - - cern.jet.stat.Probability

    public class Probability
    extends Constants

Custom tailored numerical integration of certain probability distributions.

Implementation:

Some code taken and adapted from the Java 2D Graph Package 2.4, which in turn is a port from the Cephes 2.2 Math Library (C). Most Cephes code (missing from the 2D Graph Package) directly ported.

Version:
  0.91, 08-Dec-99

### Method Summary

Methods
`static double` `beta(double a, double b, double x)` Returns the area from zero to `x` under the beta density function.
`static double` `betaComplemented(double a, double b, double x)` Returns the area under the right hand tail (from `x` to infinity) of the beta density function.
`static double` `binomial(int k, int n, double p)` Returns the sum of the terms `0` through `k` of the Binomial probability density.
`static double` `binomialComplemented(int k, int n, double p)` Returns the sum of the terms `k+1` through `n` of the Binomial probability density.
`static double` `chiSquare(double v, double x)` Returns the area under the left hand tail (from 0 to `x`) of the Chi square probability density function with `v` degrees of freedom.
`static double` `chiSquareComplemented(double v, double x)` Returns the area under the right hand tail (from `x` to infinity) of the Chi square probability density function with `v` degrees of freedom.
`static double` `errorFunction(double x)` Returns the error function of the normal distribution; formerly named `erf`.
`static double` `errorFunctionComplemented(double a)` Returns the complementary Error function of the normal distribution; formerly named `erfc`.
`static double` `gamma(double a, double b, double x)` Returns the integral from zero to `x` of the gamma probability density function.
`static double` `gammaComplemented(double a, double b, double x)` Returns the integral from `x` to infinity of the gamma probability density function:
`static double` `negativeBinomial(int k, int n, double p)` Returns the sum of the terms `0` through `k` of the Negative Binomial Distribution.
`static double` `negativeBinomialComplemented(int k, int n, double p)` Returns the sum of the terms `k+1` to infinity of the Negative Binomial distribution.
`static double` `normal(double a)` Returns the area under the Normal (Gaussian) probability density function, integrated from minus infinity to `x` (assumes mean is zero, variance is one).
`static double` `normal(double mean, double variance, double x)` Returns the area under the Normal (Gaussian) probability density function, integrated from minus infinity to `x`.
`static double` `normalInverse(double y0)` Returns the value, `x`, for which the area under the Normal (Gaussian) probability density function (integrated from minus infinity to `x`) is equal to the argument `y` (assumes mean is zero, variance is one); formerly named `ndtri`.
`static double` `poisson(int k, double mean)` Returns the sum of the first `k` terms of the Poisson distribution.
`static double` `poissonComplemented(int k, double mean)` Returns the sum of the terms `k+1` to `Infinity` of the Poisson distribution.
`static double` `studentT(double k, double t)` Returns the integral from minus infinity to `t` of the Student-t distribution with `k > 0` degrees of freedom.
`static double` `studentTInverse(double alpha, int size)` Returns the value, `t`, for which the area under the Student-t probability density function (integrated from minus infinity to `t`) is equal to `1-alpha/2`.

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

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

### Method Detail

#### beta

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

Returns the area from zero to `x` under the beta density function.

                              x
                -             -
               | (a+b)       | |  a-1      b-1
     P(x)  =  ----------     |   t    (1-t)    dt
               -     -     | |
              | (a) | (b)   -
                             0

This function is identical to the incomplete beta integral function `Gamma.incompleteBeta(a, b, x)`. The complemented function is `1 - P(1-x) = Gamma.incompleteBeta( b, a, x )`;

#### betaComplemented

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

Returns the area under the right hand tail (from `x` to infinity) of the beta density function. This function is identical to the incomplete beta integral function `Gamma.incompleteBeta(b, a, x)`.

#### binomial

    public static double binomial(int k,
                  int n,
                  double p)

Returns the sum of the terms `0` through `k` of the Binomial probability density.

       k
       --  ( n )   j      n-j
       >   (   )  p  (1-p)
       --  ( j )
      j=0

The terms are not summed directly; instead the incomplete beta integral is employed, according to the formula

`y = binomial( k, n, p ) = Gamma.incompleteBeta( n-k, k+1, 1-p )`.

All arguments must be positive,

Parameters:
  `k` - end term.
  `n` - the number of trials.
  `p` - the probability of success (must be in `(0.0,1.0)`).

#### binomialComplemented

    public static double binomialComplemented(int k,
                              int n,
                              double p)

Returns the sum of the terms `k+1` through `n` of the Binomial probability density.

       n
       --  ( n )   j      n-j
       >   (   )  p  (1-p)
       --  ( j )
      j=k+1

The terms are not summed directly; instead the incomplete beta integral is employed, according to the formula

`y = binomialComplemented( k, n, p ) = Gamma.incompleteBeta( k+1, n-k, p )`.

All arguments must be positive,

Parameters:
  `k` - end term.
  `n` - the number of trials.
  `p` - the probability of success (must be in `(0.0,1.0)`).

#### chiSquare

    public static double chiSquare(double v,
                   double x)
                            throws java.lang.ArithmeticException

Returns the area under the left hand tail (from 0 to `x`) of the Chi square probability density function with `v` degrees of freedom.

                                      inf.
                                        -
                            1          | |  v/2-1  -t/2
      P( x | v )   =   -----------     |   t      e     dt
                        v/2  -       | |
                       2    | (v/2)   -
                                       x

where `x` is the Chi-square variable.

The incomplete gamma integral is used, according to the formula

`y = chiSquare( v, x ) = incompleteGamma( v/2.0, x/2.0 )`.

The arguments must both be positive.

Parameters:
  `v` - degrees of freedom.
  `x` - integration end point.
Throws:
  `java.lang.ArithmeticException`

#### chiSquareComplemented

    public static double chiSquareComplemented(double v,
                               double x)
                                        throws java.lang.ArithmeticException

Returns the area under the right hand tail (from `x` to infinity) of the Chi square probability density function with `v` degrees of freedom.

                                      inf.
                                        -
                            1          | |  v/2-1  -t/2
      P( x | v )   =   -----------     |   t      e     dt
                        v/2  -       | |
                       2    | (v/2)   -
                                       x

where `x` is the Chi-square variable. The incomplete gamma integral is used, according to the formula `y = chiSquareComplemented( v, x ) = incompleteGammaComplement( v/2.0, x/2.0 )`. The arguments must both be positive.

Parameters:
  `v` - degrees of freedom.
Throws:
  `java.lang.ArithmeticException`

#### errorFunction

    public static double errorFunction(double x)
                                throws java.lang.ArithmeticException

Returns the error function of the normal distribution; formerly named `erf`. The integral is

                               x
                                -
                     2         | |          2
       erf(x)  =  --------     |    exp( - t  ) dt.
                  sqrt(pi)   | |
                              -
                               0

Implementation: For `0 <= |x| < 1, erf(x) = x * P4(x**2)/Q5(x**2)`; otherwise `erf(x) = 1 - erfc(x)`.

Code adapted from the Java 2D Graph Package 2.4, which in turn is a port from the Cephes 2.2 Math Library (C).

Parameters:
  `a` - the argument to the function.
Throws:
  `java.lang.ArithmeticException`

#### errorFunctionComplemented

    public static double errorFunctionComplemented(double a)
                                            throws java.lang.ArithmeticException

Returns the complementary Error function of the normal distribution; formerly named `erfc`.

      1 - erf(x) =

                               inf.
                                 -
                      2         | |          2
       erfc(x)  =  --------     |    exp( - t  ) dt
                   sqrt(pi)   | |
                               -
                                x

Implementation: For small x, `erfc(x) = 1 - erf(x)`; otherwise rational approximations are computed.

Code adapted from the Java 2D Graph Package 2.4, which in turn is a port from the Cephes 2.2 Math Library (C).

Parameters:
  `a` - the argument to the function.
Throws:
  `java.lang.ArithmeticException`

#### gamma

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

Returns the integral from zero to `x` of the gamma probability density function.

                    x
            b       -
           a       | |   b-1  -at
     y =  -----    |    t    e    dt
           -     | |
          | (b)   -
                   0

The incomplete gamma integral is used, according to the relation `y = Gamma.incompleteGamma( b, a*x )`.

Parameters:
  `a` - the paramater a (alpha) of the gamma distribution.
  `b` - the paramater b (beta, lambda) of the gamma distribution.
  `x` - integration end point.

#### gammaComplemented

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

Returns the integral from `x` to infinity of the gamma probability density function:

                   inf.
            b       -
           a       | |   b-1  -at
     y =  -----    |    t    e    dt
           -     | |
          | (b)   -
                   x

The incomplete gamma integral is used, according to the relation

y = Gamma.incompleteGammaComplement( b, a*x ).

Parameters:
  `a` - the paramater a (alpha) of the gamma distribution.
  `b` - the paramater b (beta, lambda) of the gamma distribution.
  `x` - integration end point.

#### negativeBinomial

    public static double negativeBinomial(int k,
                          int n,
                          double p)

Returns the sum of the terms `0` through `k` of the Negative Binomial Distribution.

       k
       --  ( n+j-1 )   n      j
       >   (       )  p  (1-p)
       --  (   j   )
      j=0

In a sequence of Bernoulli trials, this is the probability that `k` or fewer failures precede the `n`-th success.

The terms are not computed individually; instead the incomplete beta integral is employed, according to the formula

`y = negativeBinomial( k, n, p ) = Gamma.incompleteBeta( n, k+1, p )`. All arguments must be positive,

Parameters:
  `k` - end term.
  `n` - the number of trials.
  `p` - the probability of success (must be in `(0.0,1.0)`).

#### negativeBinomialComplemented

    public static double negativeBinomialComplemented(int k,
                                      int n,
                                      double p)

Returns the sum of the terms `k+1` to infinity of the Negative Binomial distribution.

       inf
       --  ( n+j-1 )   n      j
       >   (       )  p  (1-p)
       --  (   j   )
      j=k+1

The terms are not computed individually; instead the incomplete beta integral is employed, according to the formula

y = negativeBinomialComplemented( k, n, p ) = Gamma.incompleteBeta( k+1, n, 1-p ). All arguments must be positive,

Parameters:
  `k` - end term.
  `n` - the number of trials.
  `p` - the probability of success (must be in `(0.0,1.0)`).

#### normal

    public static double normal(double a)
                         throws java.lang.ArithmeticException

Returns the area under the Normal (Gaussian) probability density function, integrated from minus infinity to `x` (assumes mean is zero, variance is one).

                                x
                                 -
                       1        | |          2
      normal(x)  = ---------    |    exp( - t /2 ) dt
                   sqrt(2pi)  | |
                               -
                              -inf.

                 =  ( 1 + erf(z) ) / 2
                 =  erfc(z) / 2

where `z = x/sqrt(2)`. Computation is via the functions `errorFunction` and `errorFunctionComplement`.

Throws:
  `java.lang.ArithmeticException`

#### normal

    public static double normal(double mean,
                double variance,
                double x)
                         throws java.lang.ArithmeticException

Returns the area under the Normal (Gaussian) probability density function, integrated from minus infinity to `x`.

                                x
                                 -
                       1        | |                 2
      normal(x)  = ---------    |    exp( - (t-mean) / 2v ) dt
                   sqrt(2pi*v)| |
                               -
                              -inf.

where `v = variance`. Computation is via the functions `errorFunction`.

Parameters:
  `mean` - the mean of the normal distribution.
  `variance` - the variance of the normal distribution.
  `x` - the integration limit.
Throws:
  `java.lang.ArithmeticException`

#### normalInverse

    public static double normalInverse(double y0)
                                throws java.lang.ArithmeticException

Returns the value, `x`, for which the area under the Normal (Gaussian) probability density function (integrated from minus infinity to `x`) is equal to the argument `y` (assumes mean is zero, variance is one); formerly named `ndtri`.

For small arguments `0 < y < exp(-2)`, the program computes `z = sqrt( -2.0 * log(y) )`; then the approximation is `x = z - log(z)/z - (1/z) P(1/z) / Q(1/z)`. There are two rational functions P/Q, one for `0 < y < exp(-32)` and the other for `y` up to `exp(-2)`. For larger arguments, `w = y - 0.5`, and `x/sqrt(2pi) = w + w**3 R(w**2)/S(w**2))`.

Throws:
  `java.lang.ArithmeticException`

#### poisson

    public static double poisson(int k,
                 double mean)
                          throws java.lang.ArithmeticException

Returns the sum of the first `k` terms of the Poisson distribution.

       k         j
       --   -m  m
       >   e    --
       --       j!
      j=0

The terms are not summed directly; instead the incomplete gamma integral is employed, according to the relation

`y = poisson( k, m ) = Gamma.incompleteGammaComplement( k+1, m )`. The arguments must both be positive.

Parameters:
  `k` - number of terms.
  `mean` - the mean of the poisson distribution.
Throws:
  `java.lang.ArithmeticException`

#### poissonComplemented

    public static double poissonComplemented(int k,
                             double mean)
                                      throws java.lang.ArithmeticException

Returns the sum of the terms `k+1` to `Infinity` of the Poisson distribution.

      inf.       j
       --   -m  m
       >   e    --
       --       j!
      j=k+1

The terms are not summed directly; instead the incomplete gamma integral is employed, according to the formula

`y = poissonComplemented( k, m ) = Gamma.incompleteGamma( k+1, m )`. The arguments must both be positive.

Parameters:
  `k` - start term.
  `mean` - the mean of the poisson distribution.
Throws:
  `java.lang.ArithmeticException`

#### studentT

    public static double studentT(double k,
                  double t)
                           throws java.lang.ArithmeticException

Returns the integral from minus infinity to `t` of the Student-t distribution with `k > 0` degrees of freedom.

                                          t
                                          -
                                         | |
                  -                      |         2   -(k+1)/2
                 | ( (k+1)/2 )           |  (     x   )
           ----------------------        |  ( 1 + --- )        dx
                         -               |  (      k  )
           sqrt( k pi ) | ( k/2 )        |
                                       | |
                                        -
                                       -inf.

Relation to incomplete beta integral:

`1 - studentT(k,t) = 0.5 * Gamma.incompleteBeta( k/2, 1/2, z )` where `z = k/(k + t**2)`.

Since the function is symmetric about `t=0`, the area under the right tail of the density is found by calling the function with `-t` instead of `t`.

Parameters:
  `k` - degrees of freedom.
  `t` - integration end point.
Throws:
  `java.lang.ArithmeticException`

#### studentTInverse

    public static double studentTInverse(double alpha,
                         int size)

Returns the value, `t`, for which the area under the Student-t probability density function (integrated from minus infinity to `t`) is equal to `1-alpha/2`. The value returned corresponds to usual Student t-distribution lookup table for `talpha[size]`.

The function uses the studentT function to determine the return value iteratively.

Parameters:
  `alpha` - probability
  `size` - size of data set