<?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"?>
<!-- $Id: distribution.xml 1291806 2012-02-21 14:31:56Z erans $ -->
<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 provide a framework for some commonly used
          probability distributions.
        </p>
      </subsection>
      <subsection name="8.2 Distribution Framework" href="distributions">
        <p>
          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.
        </p>
        <p>
          Using a distribution object, PDF and CDF probabilities are easily computed
          using the <code>cumulativeProbability</code> methods.  For a distribution
          <code>X</code>, and a domain value, <code>x</code>,
          <code>cumulativeProbability</code> computes <code>P(X &lt;= x)</code>
          (i.e. the lower tail probability of <code>X</code>).
        </p>
<source>TDistribution t = new TDistribution(29);
double lowerTail = t.cumulativeProbability(-2.656);     // P(T &lt;= -2.656)
double upperTail = 1.0 - t.cumulativeProbability(2.75); // P(T &gt;= 2.75)</source>
        <p>
          The inverse PDF and CDF values are just as easily computed using the
          <code>inverseCumulativeProbability</code> methods.  For a distribution <code>X</code>,
          and a probability, <code>p</code>, <code>inverseCumulativeProbability</code>
          computes the domain value <code>x</code>, such that:
          <ul>
            <li><code>P(X &lt;= x) = p</code>, for continuous distributions</li>
            <li><code>P(X &lt;= x) &lt;= p</code>, for discrete distributions</li>
          </ul>
          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.
        </p>
      </subsection>
      <subsection name="8.3 User Defined Distributions" href="userdefined">
        <p>
        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
        <a href="../apidocs/org/apache/commons/math3/distribution/Distribution.html">Distribution</a>,
        <a href="../apidocs/org/apache/commons/math3/distribution/ContinuousDistribution.html">
        ContinuousDistribution</a>,
        <a href="../apidocs/org/apache/commons/math3/distribution/DiscreteDistribution.html">
        DiscreteDistribution</a>, and <a href="../apidocs/org/apache/commons/math3/distribution/IntegerDistribution.html">
        IntegerDistribution</a> 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,
        the <a href="../apidocs/org/apache/commons/math3/distribution/AbstractDistribution.html">
        AbstractDistribution</a>, <a href="../apidocs/org/apache/commons/math3/distribution/AbstractContinuousDistribution.html">
        AbstractContinuousDistribution</a>, and <a href="../apidocs/org/apache/commons/math3/distribution/AbstractIntegerDistribution.html">
        AbstractIntegerDistribution</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>
