diff --git a/src/site/xdoc/userguide/distribution.xml b/src/site/xdoc/userguide/distribution.xml index a61fa7028..b862fc4fc 100644 --- a/src/site/xdoc/userguide/distribution.xml +++ b/src/site/xdoc/userguide/distribution.xml @@ -27,7 +27,7 @@

- The distributions package provide a framework for some commonly used + The distributions package provides a framework and implementations for some commonly used probability distributions.

@@ -38,49 +38,54 @@

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. + functions (density(·)), probability mass functions + (probability(·)) and distribution functions + (cumulativeProbability(·)) for both + discrete (integer-valued) and continuous probability distributions. + The framework also allows for the computation of inverse cumulative probabilities.

- 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). + For an instance f of a distribution F, + and a domain value, x, f.cumulativeProbability(x) + computes P(X <= x) where X is a random variable distributed + as f, i.e., f.cumulativeProbability(·) represents + the distribution function of f. If f is continuous, + (implementing the RealDistribution interface) the probability density + function of f is represented by f.density(·). + For discrete f (implementing IntegerDistribution), the probability + mass function is represented by f.probability(·). Continuous + distributions also implement probability(·) with the same + definition (f.probability(x) represents P(X = x) + where X is distributed as f), though in the continuous + case, this will usually be identically 0.

TDistribution t = new TDistribution(29); -double lowerTail = t.cumulativeProbability(-2.656); // P(T <= -2.656) -double upperTail = 1.0 - t.cumulativeProbability(2.75); // P(T >= 2.75) +double lowerTail = t.cumulativeProbability(-2.656); // P(T(29) <= -2.656) +double upperTail = 1.0 - t.cumulativeProbability(2.75); // P(T(29) >= 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: -

- 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. + Inverse distribution functions can be computed using the + inverseCumulativeProbability methods. For continuous f + and p a probability, f.inverseCumulativeProbability(p) returns +
    +
  • inf{x in R | P(X≤x) ≥ p} for 0 < p < 1},
    • +
  • inf{x in R | P(X≤x) > 0} for p = 0}.
    • +
where X is distributed as f.
+ For discrete f, the definition is the same, with Z (the integers) + in place of R. Note that in the discrete case, the ≥ in the definition + can make a difference when p is an attained value of the distribution.

+

- 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 + User-defined distributions can be implemented using RealDistribution, IntegerDistribution and MultivariateRealDistribution - 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 ensure any extension is compatible with the - remainder of Commons-Math. To aid in implementing a distribution extension, + interfaces serve as base types. These serve as the basis for all the distributions directly supported by + Apache Commons Math. To aid in implementing distributions, the AbstractRealDistribution, AbstractIntegerDistribution and AbstractMultivariateRealDistribution