[commons-statistics] 08/13: Document exponential as using the mean (scale) paramterization.

[ah...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

aherbert pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-statistics.git

commit 2bae640935782bf9e644d93f862f8f6aa93ff47a
Author: aherbert <ah...@apache.org>
AuthorDate: Mon Sep 20 15:41:02 2021 +0100

    Document exponential as using the mean (scale) paramterization.
    
    The alternative of the rate parameterization is noted in the class
    header.
---
 .../distribution/ExponentialDistribution.java           | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

diff --git a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/ExponentialDistribution.java b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/ExponentialDistribution.java
index 295a03d..84ba2be 100644
--- a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/ExponentialDistribution.java
+++ b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/ExponentialDistribution.java
@@ -21,6 +21,10 @@ import org.apache.commons.rng.sampling.distribution.ZigguratSampler;
 
 /**
  * Implementation of the <a href="http://en.wikipedia.org/wiki/Exponential_distribution">exponential distribution</a>.
+ *
+ * <p>This implementation uses the scale parameter {@code μ} which is the mean of the distribution.
+ * A common alternative parameterization uses the rate parameter {@code λ} which is the reciprocal
+ * of the mean.
  */
 public class ExponentialDistribution extends AbstractContinuousDistribution {
     /** Support lower bound. */
@@ -35,7 +39,7 @@ public class ExponentialDistribution extends AbstractContinuousDistribution {
     /**
      * Creates a distribution.
      *
-     * @param mean Mean of this distribution.
+     * @param mean Mean of this distribution. This is a scale parameter.
      * @throws IllegalArgumentException if {@code mean <= 0}.
      */
     public ExponentialDistribution(double mean) {
@@ -109,7 +113,11 @@ public class ExponentialDistribution extends AbstractContinuousDistribution {
         return -mean * Math.log1p(-p);
     }
 
-    /** {@inheritDoc} */
+    /**
+     * {@inheritDoc}
+     *
+     * @return the mean
+     */
     @Override
     public double getMean() {
         return mean;
@@ -118,7 +126,8 @@ public class ExponentialDistribution extends AbstractContinuousDistribution {
     /**
      * {@inheritDoc}
      *
-     * <p>For mean parameter {@code k}, the variance is {@code k^2}.
+     * <p>For mean {@code k}, the variance is {@code k^2}.
+     * @return the variance
      */
     @Override
     public double getVariance() {
@@ -166,6 +175,6 @@ public class ExponentialDistribution extends AbstractContinuousDistribution {
     @Override
     public ContinuousDistribution.Sampler createSampler(final UniformRandomProvider rng) {
         // Exponential distribution sampler.
-        return ZigguratSampler.Exponential.of(rng, mean)::sample;
+        return ZigguratSampler.Exponential.of(rng, getMean())::sample;
     }
 }