Fixed some errors; changed to use standard terminology.

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/math/trunk@1540566 13f79535-47bb-0310-9956-ffa450edef68

src/site/xdoc/userguide/distribution.xml

@@ -27,7 +27,7 @@
     <section name="8 Probability Distributions">
       <subsection name="8.1 Overview" href="overview">
         <p>
-          The distributions package provide a framework for some commonly used
+          The distributions package provides a framework and implementations for some commonly used
           probability distributions.
         </p>
         <p>
@@ -38,49 +38,54 @@
       <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)
+          functions (<code>density(&middot;)</code>), probability mass functions
-          probabilities for common probability distributions. Along with the direct
+          (<code>probability(&middot;)</code>) and distribution functions
-          computation of PDF and CDF probabilities, the framework also allows for the
+          (<code>cumulativeProbability(&middot;)</code>) for both
-          computation of inverse PDF and inverse CDF values.
+          discrete (integer-valued) and continuous probability distributions.
+          The framework also allows for the computation of inverse cumulative probabilities.
         </p>
         <p>
-          Using a distribution object, PDF and CDF probabilities are easily computed
+          For an instance <code>f</code> of a distribution <code>F</code>,
-          using the <code>cumulativeProbability</code> methods.  For a distribution
+          and a domain value, <code>x</code>, <code>f.cumulativeProbability(x)</code>
-          <code>X</code>, and a domain value, <code>x</code>,
+          computes <code>P(X &lt;= x)</code> where <code>X</code> is a random variable distributed
-          <code>cumulativeProbability</code> computes <code>P(X &lt;= x)</code>
+          as <code>f</code>, i.e., <code>f.cumulativeProbability(&middot;)</code> represents
-          (i.e. the lower tail probability of <code>X</code>).
+          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(&middot;)</code>.
+          For discrete <code>f</code> (implementing <code>IntegerDistribution</code>), the probability
+          mass function is represented by <code>f.probability(&middot;)</code>.  Continuous
+          distributions also implement <code>probability(&middot;)</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 &lt;= -2.656)
+double lowerTail = t.cumulativeProbability(-2.656);     // P(T(29) &lt;= -2.656)
-double upperTail = 1.0 - t.cumulativeProbability(2.75); // P(T &gt;= 2.75)</source>
+double upperTail = 1.0 - t.cumulativeProbability(2.75); // P(T(29) &gt;= 2.75)</source>
         <p>
-          The inverse PDF and CDF values are just as easily computed using the
+          Inverse distribution functions can be computed using the
-          <code>inverseCumulativeProbability</code> methods.  For a distribution <code>X</code>,
+          <code>inverseCumulativeProbability</code> methods.  For continuous <code>f</code>
-          and a probability, <code>p</code>, <code>inverseCumulativeProbability</code>
+          and <code>p</code> a probability, <code>f.inverseCumulativeProbability(p)</code> returns
-          computes the domain value <code>x</code>, such that:
+          <code><ul>
-          <ul>
+            <li>inf{x in R | P(X&le;x) &ge; p} for 0 &lt; p &lt; 1},</li>
-            <li><code>P(X &lt;= x) = p</code>, for continuous distributions</li>
+            <li>inf{x in R | P(X&le;x) &gt; 0} for p = 0}.</li>
-            <li><code>P(X &lt;= x) &lt;= p</code>, for discrete distributions</li>
+          </ul></code> where <code>X</code> is distributed as <code>f</code>.<br/>
-          </ul>
+          For discrete <code>f</code>, the definition is the same, with <code>Z</code> (the integers)
-          Notice the different cases for continuous and discrete distributions.  This is the result
+          in place of <code>R</code>.  Note that in the discrete case, the &ge; in the definition
-          of PDFs not being invertible functions.  As such, for discrete distributions, an exact
+          can make a difference when <code>p</code> is an attained value of the distribution.
-          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>
+      <!--
+          TODO: add section on multivariate distributions
+      -->
       <subsection name="8.3 User Defined Distributions" href="userdefined">
         <p>
-        Since there are numerous distributions and Commons-Math only directly
+        User-defined distributions can be implemented using
-        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/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 for any extension.  These serve as the basis for all the
+        interfaces serve as base types.  These serve as the basis for all the distributions directly supported by
-        distributions directly supported by Commons-Math and using those interfaces
+        Apache Commons Math.  To aid in implementing distributions,
-        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/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>