| <?xml version="1.0"?> |
| |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| <?xml-stylesheet type="text/xsl" href="./xdoc.xsl"?> |
| <document url="distribution.html"> |
| <properties> |
| <title>The Commons Math User Guide - Distributions</title> |
| </properties> |
| <body> |
| <section name="8 Probability Distributions"> |
| <subsection name="8.1 Overview" href="overview"> |
| <p> |
| The distributions package provides a framework and implementations for some commonly used |
| probability distributions. Continuous univariate distributions are represented by implementations of |
| the <a href="../apidocs/org/apache/commons/math3/distribution/RealDistribution.html">RealDistribution</a> |
| interface. Discrete distributions implement |
| <a href="../apidocs/org/apache/commons/math3/distribution/IntegerDistribution.html">IntegerDistribution</a> |
| (values must be mapped to integers) and there is an |
| <a href="../apidocs/org/apache/commons/math3/distribution/EnumeratedDistribution.html">EnumeratedDistribution</a> |
| class representing discrete distributions with a finite, enumerated set of values. Finally, multivariate |
| real-valued distributions can be represented via the |
| <a href="../apidocs/org/apache/commons/math3/distribution/MultiVariateRealDistribution.html">MultivariateRealDistribution</a> |
| interface. |
| </p> |
| <p> |
| An overview of available continuous distributions:<br/> |
| <img src="../images/userguide/real_distribution_examples.png" alt="Overview of continuous distributions"/> |
| </p> |
| </subsection> |
| <subsection name="8.2 Distribution Framework" href="distributions"> |
| <p> |
| The distribution framework provides the means to compute probability density |
| functions (<code>density(·)</code>), probability mass functions |
| (<code>probability(·)</code>) and distribution functions |
| (<code>cumulativeProbability(·)</code>) for both |
| discrete (integer-valued) and continuous probability distributions. |
| The framework also allows for the computation of inverse cumulative probabilities |
| and sampling from distributions. |
| </p> |
| <p> |
| For an instance <code>f</code> of a distribution <code>F</code>, |
| and a domain value, <code>x</code>, <code>f.cumulativeProbability(x)</code> |
| computes <code>P(X <= x)</code> where <code>X</code> is a random variable distributed |
| as <code>f</code>, i.e., <code>f.cumulativeProbability(·)</code> represents |
| the distribution function of <code>f</code>. If <code>f</code> is continuous, |
| (implementing the <code>RealDistribution</code> interface) the probability density |
| function of <code>f</code> is represented by <code>f.density(·)</code>. |
| For discrete <code>f</code> (implementing <code>IntegerDistribution</code>), the probability |
| mass function is represented by <code>f.probability(·)</code>. Continuous |
| distributions also implement <code>probability(·)</code> with the same |
| definition (<code>f.probability(x)</code> represents <code>P(X = x)</code> |
| where <code>X</code> is distributed as <code>f</code>), though in the continuous |
| case, this will usually be identically 0. |
| </p> |
| <source>TDistribution t = new TDistribution(29); |
| double lowerTail = t.cumulativeProbability(-2.656); // P(T(29) <= -2.656) |
| double upperTail = 1.0 - t.cumulativeProbability(2.75); // P(T(29) >= 2.75)</source> |
| <p> |
| All distributions implement a <code>sample()</code> method to support random sampling from the |
| distribution. Implementation classes expose constructors allowing the default |
| <a href="../apidocs/org/apache/commons/math3/random/RandomGenerator.html">RandomGenerator</a> |
| used by the sampling algorithm to be overridden. If sampling is not going to be used, providing |
| a null <code>RandomGenerator</code> constructor argument will avoid the overhead of initializing |
| the default generator. |
| </p> |
| <p> |
| Inverse distribution functions can be computed using the |
| <code>inverseCumulativeProbability</code> methods. For continuous <code>f</code> |
| and <code>p</code> a probability, <code>f.inverseCumulativeProbability(p)</code> returns |
| <code><ul> |
| <li>inf{x in R | P(X≤x) ≥ p} for 0 < p < 1},</li> |
| <li>inf{x in R | P(X≤x) > 0} for p = 0}.</li> |
| </ul></code> where <code>X</code> is distributed as <code>f</code>.<br/> |
| For discrete <code>f</code>, the definition is the same, with <code>Z</code> (the integers) |
| in place of <code>R</code>. Note that in the discrete case, the ≥ in the definition |
| can make a difference when <code>p</code> is an attained value of the distribution. |
| </p> |
| </subsection> |
| <!-- |
| TODO: add section on multivariate distributions |
| --> |
| <subsection name="8.3 User Defined Distributions" href="userdefined"> |
| <p> |
| User-defined distributions can be implemented using |
| <a href="../apidocs/org/apache/commons/math3/distribution/RealDistribution.html">RealDistribution</a>, |
| <a href="../apidocs/org/apache/commons/math3/distribution/IntegerDistribution.html">IntegerDistribution</a> and |
| <a href="../apidocs/org/apache/commons/math3/distribution/MultivariateRealDistribution.html">MultivariateRealDistribution</a> |
| 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 <a href="../apidocs/org/apache/commons/math3/distribution/AbstractRealDistribution.html">AbstractRealDistribution</a>, |
| <a href="../apidocs/org/apache/commons/math3/distribution/AbstractIntegerDistribution.html">AbstractIntegerDistribution</a> and |
| <a href="../apidocs/org/apache/commons/math3/distribution/AbstractMultivariateRealDistribution.html">AbstractMultivariateRealDistribution</a> |
| provide implementation building blocks and offer basic distribution functionality. |
| By extending these abstract classes directly, much of the repetitive distribution |
| implementation is already developed and should save time and effort in developing |
| user-defined distributions. |
| </p> |
| </subsection> |
| </section> |
| </body> |
| </document> |
