The Commons Math User Guide - Statistics

The distributions package provide a framework for some commonly used probability distributions.

The distribution framework provides the means to compute probability density function (PDF) probabilities and cumulative distribution function (CDF) probabilities for common probability distributions. Along with the direct computation of PDF and CDF probabilities, the framework also allows for the computation of inverse PDF and inverse CDF values.

In order to use the distribution framework, first a distribution object must be created. It is encouraged that all distribution object creation occurs via the org.apache.commons.math.distribution.DistributionFactory class. DistributionFactory is a simple factory used to create all of the distribution objects supported by Commons-Math. The typical usage of DistributionFactory to create a distribution object would be:

DistributionFactory factory = DistributionFactory.newInstance(); BinomialDistribution binomial = factory.createBinomialDistribution(10, .75);

The distributions that can be instantiated via the DistributionFactory are detailed below:
DistributionFactory MethodParameters
BinomialcreateBinomialDistribution
Number of trials
Probability of success
CauchycreateCauchyDistribution
Median
Scale
Chi-SquaredcreateChiSquaredDistribution
Degrees of freedom
ExponentialcreateExponentialDistribution
Mean
FcreateFDistribution
Numerator degrees of freedom
Denominator degrees of freedom
GammacreateGammaDistribution
Alpha
Beta
HypergeometriccreateHypogeometricDistribution
Population size
Number of successes in population
Sample size
Normal (Gaussian)createNormalDistribution
Mean
Standard Deviation
PoissoncreatePoissonDistribution
Mean
tcreateTDistribution
Degrees of freedom

Using a distribution object, PDF and CDF probabilities are easily computed using the cumulativeProbability methods. For a distribution X, and a domain value, x, cumulativeProbability computes P(X <= x) (i.e. the lower tail probability of X).

DistributionFactory factory = DistributionFactory.newInstance(); TDistribution t = factory.createBinomialDistribution(29); double lowerTail = t.cumulativeProbability(-2.656); // P(T <= -2.656) double upperTail = 1.0 - t.cumulativeProbability(2.75); // P(T >= 2.75)

The inverse PDF and CDF values are just as easily computed using the inverseCumulativeProbabilitymethods. For a distribution X, and a probability, p, inverseCumulativeProbability computes the domain value x, such that:

  • P(X <= x) = p, for continuous distributions
  • P(X <= x) <= p, for discrete distributions
Notice the different cases for continuous and discrete distributions. This is the result of PDFs not being invertible functions. As such, for discrete distributions, an exact domain value can not be returned. Only the "best" domain value. For Commons-Math, the "best" domain value is determined by the largest domain value whose cumulative probability is less-than or equal to the given probability.

Since there are numerous distributions and Commons-Math only directly supports a handful, it may be necessary to extend the distribution framework to satisfy individual needs. It is recommended that the Distribution, ContinuousDistribution, DiscreteDistribution, and IntegerDistribution interfaces serve as base types for any extension. These serve as the basis for all the distributions directly supported by Commons-Math and using those interfaces for implementation purposes will insure any extension is compatible with the remainder of Commons-Math. To aid in implementing a distribution extension, the AbstractDistribution, AbstractContinuousDistribution, and AbstractIntegerDistribution provide implementation building blocks and offer a lot of default distribution functionality. By extending these abstract classes directly, a good portion of the repetitive distribution implementation is already developed and should save time and effort in developing user defined distributions.