About Us Home Contributors License Components Sandbox Math Overview Proposal Developers Guide Javadoc Tasks: To Do User Guide Contents Overview Statistics Data Generation Linear Algebra Numerical Analysis Special Functions Utilities Complex Numbers Distributions Project Documentation About Math Project Info Project Reports Development Process General Information Charter Volunteering Contributing Patches Releasing Components Jakarta Community Get Involved Mailing Lists Access CVS Repositories Commons Resources (Unofficial) Wiki Japanese Translation Korean Translation Related Apache Commons DB Commons XML Commons | ### 8 Probability Distributions #### 8.1 Overview The distributions package provide a framework for some commonly used probability distributions. #### 8.2 Distribution Framework 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:
Distribution | Factory Method | Parameters
--- | --- | ---
Binomial | createBinomialDistribution | Number of trials Probability of success
Chi-Squared | createChiSquaredDistribution | Degrees of freedom
Exponential | createExponentialDistribution | Mean
F | createFDistribution | Numerator degrees of freedom Denominator degrees of freedom
Gamma | createGammaDistribution | Alpha Beta
Hypergeometric | createHypogeometricDistribution | Population size Number of successes in population Sample size
Normal (Gaussian) | createNormalDistribution | Mean Standard Deviation
Poisson | createPoissonDistribution | Mean
t | createTDistribution | 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 `inverseCumulativeProbability`methods. 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. #### 8.3 User Defined Distributions 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.