You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by ah...@apache.org on 2021/12/17 21:46:17 UTC
[commons-statistics] 01/05: Add PDF and PMF to distribution class javadoc
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 65e547c4008775953efa7d8a960e8b36d57e213e
Author: Alex Herbert <ah...@apache.org>
AuthorDate: Wed Dec 15 22:36:15 2021 +0000
Add PDF and PMF to distribution class javadoc
---
.../statistics/distribution/BetaDistribution.java | 3 +-
.../distribution/BinomialDistribution.java | 12 ++++++
.../distribution/CauchyDistribution.java | 8 ++++
.../distribution/ChiSquaredDistribution.java | 8 ++++
.../distribution/ExponentialDistribution.java | 11 ++++-
.../statistics/distribution/FDistribution.java | 7 ++++
.../statistics/distribution/GammaDistribution.java | 7 ++++
.../distribution/GeometricDistribution.java | 10 +++++
.../distribution/GumbelDistribution.java | 10 +++++
.../distribution/HypergeometricDistribution.java | 13 ++++++
.../distribution/LaplaceDistribution.java | 8 ++++
.../statistics/distribution/LevyDistribution.java | 8 ++++
.../distribution/LogNormalDistribution.java | 23 ++++------
.../distribution/LogisticDistribution.java | 8 ++++
.../distribution/NakagamiDistribution.java | 8 ++++
.../distribution/NormalDistribution.java | 8 ++++
.../distribution/ParetoDistribution.java | 4 +-
.../distribution/PascalDistribution.java | 38 ++++++++++-------
.../distribution/PoissonDistribution.java | 7 ++++
.../statistics/distribution/TDistribution.java | 8 ++++
.../distribution/TriangularDistribution.java | 13 +++++-
.../distribution/TruncatedNormalDistribution.java | 11 +++++
.../UniformContinuousDistribution.java | 7 ++++
.../distribution/UniformDiscreteDistribution.java | 7 ++++
.../distribution/WeibullDistribution.java | 49 ++++++++++++----------
.../statistics/distribution/ZipfDistribution.java | 24 +++++------
26 files changed, 252 insertions(+), 68 deletions(-)
diff --git a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/BetaDistribution.java b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/BetaDistribution.java
index b67425f..742c929 100644
--- a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/BetaDistribution.java
+++ b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/BetaDistribution.java
@@ -28,7 +28,8 @@ import org.apache.commons.rng.sampling.distribution.ChengBetaSampler;
*
* <p>\[ f(x; \alpha, \beta) = \frac{1}{ B(\alpha, \beta)} x^{\alpha-1} (1-x)^{\beta-1} \]
*
- * <p>for \( \alpha > 0 \), \( \beta > 0 \), \( x \in [0, 1] \) and
+ * <p>for \( \alpha > 0 \),
+ * \( \beta > 0 \), \( x \in [0, 1] \), and
* the beta function, \( B \), is a normalization constant:
*
* <p>\[ B(\alpha, \beta) = \frac{\Gamma(\alpha+\beta)}{\Gamma(\alpha) \Gamma(\beta)} \]
diff --git a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/BinomialDistribution.java b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/BinomialDistribution.java
index d59e237..19698e2 100644
--- a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/BinomialDistribution.java
+++ b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/BinomialDistribution.java
@@ -20,6 +20,18 @@ import org.apache.commons.numbers.gamma.RegularizedBeta;
/**
* Implementation of the <a href="http://en.wikipedia.org/wiki/Binomial_distribution">binomial distribution</a>.
+ *
+ * <p>The probability mass function of \( X \) is:
+ *
+ * <p>\[ f(k; n, p) = \binom{n}{k} p^k (1-p)^{n-k} \]
+ *
+ * <p>for \( n \in \{0, 1, 2, \dots\} \) the number of trials,
+ * \( p \in [0, 1] \) the probability of success,
+ * \( k \in \{0, 1, \dots, n\} \) the number of successes, and
+ *
+ * <p>\[ \binom{n}{k} = \frac{n!}{k! \, (n-k)!} \]
+ *
+ * <p>is the binomial coefficient.
*/
public final class BinomialDistribution extends AbstractDiscreteDistribution {
/** The number of trials. */
diff --git a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/CauchyDistribution.java b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/CauchyDistribution.java
index ca766be..9ec0506 100644
--- a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/CauchyDistribution.java
+++ b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/CauchyDistribution.java
@@ -21,6 +21,14 @@ import org.apache.commons.rng.sampling.distribution.StableSampler;
/**
* Implementation of the <a href="http://en.wikipedia.org/wiki/Cauchy_distribution">Cauchy distribution</a>.
+ *
+ * <p>The probability density function of \( X \) is:
+ *
+ * <p>\[ f(x; x_0, \gamma) = { 1 \over \pi \gamma } \left[ { \gamma^2 \over (x - x_0)^2 + \gamma^2 } \right] \]
+ *
+ * <p>for \( x_0 \) the location,
+ * \( \gamma > 0 \) the scale, and
+ * \( x \in (-\infty, \infty) \).
*/
public final class CauchyDistribution extends AbstractContinuousDistribution {
/** The location of this distribution. */
diff --git a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/ChiSquaredDistribution.java b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/ChiSquaredDistribution.java
index fa86783..1261522 100644
--- a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/ChiSquaredDistribution.java
+++ b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/ChiSquaredDistribution.java
@@ -20,6 +20,14 @@ import org.apache.commons.rng.UniformRandomProvider;
/**
* Implementation of the <a href="http://en.wikipedia.org/wiki/Chi-squared_distribution">chi-squared distribution</a>.
+ *
+ * <p>The probability density function of \( X \) is:
+ *
+ * <p>\[ f(x; k) = \frac{1}{2^{k/2} \Gamma(k/2)} x^{k/2 -1} e^{-x/2} \]
+ *
+ * <p>for \( k > 0 \) the degrees of freedom,
+ * \( \Gamma(k/2) \) is the gamma function, and
+ * \( x \in [0, \infty) \).
*/
public final class ChiSquaredDistribution extends AbstractContinuousDistribution {
/** Internal Gamma distribution. */
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 1f04867..93d51d2 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
@@ -22,8 +22,15 @@ 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
+ * <p>The probability density function of \( X \) is:
+ *
+ * <p>\[ f(x; \mu) = \frac{1}{\mu} e^{-x / \mu} \]
+ *
+ * <p>for \( \mu > 0 \) the mean and
+ * \( x \in [0, \infty) \).
+ *
+ * <p>This implementation uses the scale parameter \( \mu \) which is the mean of the distribution.
+ * A common alternative parameterization uses the rate parameter \( \lambda \) which is the reciprocal
* of the mean.
*/
public final class ExponentialDistribution extends AbstractContinuousDistribution {
diff --git a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/FDistribution.java b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/FDistribution.java
index b548af7..19b5df3 100644
--- a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/FDistribution.java
+++ b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/FDistribution.java
@@ -23,6 +23,13 @@ import org.apache.commons.numbers.gamma.RegularizedBeta;
/**
* Implementation of the F-distribution.
*
+ * <p>The probability density function of \( X \) is:
+ *
+ * <p>\[ f(x; d_1, d_2) = \frac{1}{\operatorname{B}\left(\frac{d_1}{2},\frac{d_2}{2}\right)} \left(\frac{d_1}{d_2}\right)^{d_1/2} x^{d_1/2 - 1} \left(1+\frac{d_1}{d_2} \, x \right)^{-(d_1+d_2)/2} \]
+ *
+ * <p>for \( d_1, d_2 > 0 \) the degrees of freedom, \( \operatorname{B}(d_1 / 2, d_2 / 2) \) is the beta function,
+ * and \( x \in [0, \infty) \).
+ *
* @see <a href="http://en.wikipedia.org/wiki/F-distribution">F-distribution (Wikipedia)</a>
* @see <a href="http://mathworld.wolfram.com/F-Distribution.html">F-distribution (MathWorld)</a>
*/
diff --git a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/GammaDistribution.java b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/GammaDistribution.java
index 63bf630..12f94cd 100644
--- a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/GammaDistribution.java
+++ b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/GammaDistribution.java
@@ -23,6 +23,13 @@ import org.apache.commons.rng.sampling.distribution.AhrensDieterMarsagliaTsangGa
/**
* Implementation of the <a href="http://en.wikipedia.org/wiki/Gamma_distribution">gamma distribution</a>.
+ *
+ * <p>The probability density function of \( X \) is:
+ *
+ * <p>\[ f(x;k,\theta) = \frac{x^{k-1}e^{-x/\theta}}{\theta^k\Gamma(k)} \]
+ *
+ * <p>for \( k > 0 \) the shape, \( \theta > 0 \) the scale, \( \Gamma(k) \) is the gamma function
+ * and \( x \in (0, \infty) \).
*/
public final class GammaDistribution extends AbstractContinuousDistribution {
/** Support lower bound. */
diff --git a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/GeometricDistribution.java b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/GeometricDistribution.java
index 7d9e623..b7bc116 100644
--- a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/GeometricDistribution.java
+++ b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/GeometricDistribution.java
@@ -22,6 +22,16 @@ import org.apache.commons.rng.sampling.distribution.GeometricSampler;
/**
* Implementation of the <a href="http://en.wikipedia.org/wiki/Geometric_distribution">geometric distribution</a>.
+ *
+ * <p>The probability mass function of \( X \) is:
+ *
+ * <p>\[ f(k; p) = (1-p)^k \, p \]
+ *
+ * <p>for \( p \in (0, 1] \) the probability of success and
+ * \( k \in \{0, 1, 2, \dots\} \) the number of failures.
+ *
+ * <p>This parameterization is used to model the number of failures until
+ * the first success.
*/
public final class GeometricDistribution extends AbstractDiscreteDistribution {
/** 1/2. */
diff --git a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/GumbelDistribution.java b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/GumbelDistribution.java
index 59127b3..b44e6e4 100644
--- a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/GumbelDistribution.java
+++ b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/GumbelDistribution.java
@@ -18,6 +18,16 @@ package org.apache.commons.statistics.distribution;
/**
* This class implements the <a href="http://en.wikipedia.org/wiki/Gumbel_distribution">Gumbel distribution</a>.
+ *
+ * <p>The probability density function of \( X \) is:
+ *
+ * <p>\[ f(x; \mu, \beta) = \frac{1}{\beta} e^{-(z+e^{-z})} \]
+ *
+ * <p>where \[ z = \frac{x - \mu}{\beta} \]
+ *
+ * <p>for \( \mu \) the location,
+ * \( \beta > 0 \) the scale, and
+ * \( x \in (-\infty, \infty) \).
*/
public final class GumbelDistribution extends AbstractContinuousDistribution {
/** Support lower bound. */
diff --git a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/HypergeometricDistribution.java b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/HypergeometricDistribution.java
index 8d9c1d5..f551a1f 100644
--- a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/HypergeometricDistribution.java
+++ b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/HypergeometricDistribution.java
@@ -19,6 +19,19 @@ package org.apache.commons.statistics.distribution;
/**
* Implementation of the <a href="http://en.wikipedia.org/wiki/Hypergeometric_distribution">hypergeometric distribution</a>.
+ *
+ * <p>The probability mass function of \( X \) is:
+ *
+ * <p>\[ f(k; n, p) = \frac{\binom{K}{k} \binom{N - K}{n-k}}{\binom{N}{n}} \]
+ *
+ * <p>for \( N \in \{0, 1, 2, \dots\} \) the population size,
+ * \( K \in \{0, 1, \dots, N\} \) the number of success states,
+ * \( n \in \{0, 1, \dots, N\} \) the number of samples,
+ * \( k \in \{\max(0, n+K-N), \dots, \min(n, K)\} \) the number of successes, and
+ *
+ * <p>\[ \binom{a}{b} = \frac{a!}{b! \, (a-b)!} \]
+ *
+ * <p>is the binomial coefficient.
*/
public final class HypergeometricDistribution extends AbstractDiscreteDistribution {
/** The number of successes in the population. */
diff --git a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/LaplaceDistribution.java b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/LaplaceDistribution.java
index c66a481..675a90e 100644
--- a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/LaplaceDistribution.java
+++ b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/LaplaceDistribution.java
@@ -19,6 +19,14 @@ package org.apache.commons.statistics.distribution;
/**
* This class implements the Laplace distribution.
*
+ * <p>The probability density function of \( X \) is:
+ *
+ * <p>\[ f(x; \mu, b) = \frac{1}{2b} \exp \left( -\frac{|x-\mu|}{b} \right) \]
+ *
+ * <p>for \( \mu \) the location,
+ * \( b > 0 \) the scale, and
+ * \( x \in (-\infty, \infty) \).
+ *
* @see <a href="http://en.wikipedia.org/wiki/Laplace_distribution">Laplace distribution (Wikipedia)</a>
*/
public final class LaplaceDistribution extends AbstractContinuousDistribution {
diff --git a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/LevyDistribution.java b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/LevyDistribution.java
index d4ab4cf..83644c6 100644
--- a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/LevyDistribution.java
+++ b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/LevyDistribution.java
@@ -26,6 +26,14 @@ import org.apache.commons.rng.sampling.distribution.LevySampler;
/**
* This class implements the <a href="http://en.wikipedia.org/wiki/L%C3%A9vy_distribution">
* Lévy distribution</a>.
+ *
+ * <p>The probability density function of \( X \) is:
+ *
+ * <p>\[ f(x; \mu, c) = \sqrt{\frac{c}{2\pi}}~~\frac{e^{ -\frac{c}{2(x-\mu)}}} {(x-\mu)^{3/2}} \]
+ *
+ * <p>for \( \mu \) the location,
+ * \( c > 0 \) the scale, and
+ * \( x \in [\mu, \infty) \).
*/
public final class LevyDistribution extends AbstractContinuousDistribution {
/** 1 / 2(erfc^-1 (0.5))^2. Computed using Matlab's VPA to 30 digits. */
diff --git a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/LogNormalDistribution.java b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/LogNormalDistribution.java
index 4f5681f..fb285d1 100644
--- a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/LogNormalDistribution.java
+++ b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/LogNormalDistribution.java
@@ -26,20 +26,15 @@ import org.apache.commons.rng.sampling.distribution.ZigguratSampler;
/**
* Implementation of the <a href="http://en.wikipedia.org/wiki/Log-normal_distribution">log-normal distribution</a>.
*
- * <p>
- * <strong>Parameters:</strong>
- * {@code X} is log-normally distributed if its natural logarithm {@code log(X)}
- * is normally distributed. The probability distribution function of {@code X}
- * is given by (for {@code x > 0})
- * </p>
- * <p>
- * {@code exp(-0.5 * ((ln(x) - mu) / s)^2) / (s * sqrt(2 * pi) * x)}
- * </p>
- * <ul>
- * <li>{@code mu} is the mean of the normally distributed natural logarithm of this distribution,</li>
- * <li>{@code s} is standard deviation of the normally distributed natural logarithm of this
- * distribution.
- * </ul>
+ * <p>\( X \) is log-normally distributed if its natural logarithm \( \ln(x) \)
+ * is normally distributed. The probability density function of \( X \) is:
+ *
+ * <p>\[ f(x; \mu, \sigma) = \frac 1 {x\sigma\sqrt{2\pi\,}} e^{-{\frac 1 2}\left( \frac{\ln x-\mu}{\sigma} \right)^2 } \]
+ *
+ * <p>for \( \mu \) the mean of the normally distributed natural logarithm of this distribution,
+ * \( \sigma > 0 \) the standard deviation of the normally distributed natural logarithm of this
+ * distribution, and
+ * \( x \in (0, \infty) \).
*/
public final class LogNormalDistribution extends AbstractContinuousDistribution {
/** 0.5 * ln(2 * pi). Computed to 25-digits precision. */
diff --git a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/LogisticDistribution.java b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/LogisticDistribution.java
index 5ccd850..57332fe 100644
--- a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/LogisticDistribution.java
+++ b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/LogisticDistribution.java
@@ -18,6 +18,14 @@ package org.apache.commons.statistics.distribution;
/**
* Implementation of the <a href="http://en.wikipedia.org/wiki/Logistic_distribution">logistic distribution</a>.
+ *
+ * <p>The probability density function of \( X \) is:
+ *
+ * <p>\[ f(x; \mu, s) = \frac{e^{-(x-\mu)/s}} {s\left(1+e^{-(x-\mu)/s}\right)^2} \]
+ *
+ * <p>for \( \mu \) the location,
+ * \( s > 0 \) the scale, and
+ * \( x \in (-\infty, \infty) \).
*/
public final class LogisticDistribution extends AbstractContinuousDistribution {
/** Support lower bound. */
diff --git a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/NakagamiDistribution.java b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/NakagamiDistribution.java
index 6f32b9a..f8c64a5 100644
--- a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/NakagamiDistribution.java
+++ b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/NakagamiDistribution.java
@@ -22,6 +22,14 @@ import org.apache.commons.numbers.gamma.RegularizedGamma;
/**
* This class implements the <a href="http://en.wikipedia.org/wiki/Nakagami_distribution">Nakagami distribution</a>.
+ *
+ * <p>The probability density function of \( X \) is:
+ *
+ * <p>\[ f(x; \mu, \Omega) = \frac{2\mu^\mu}{\Gamma(\mu)\Omega^\mu}x^{2\mu-1}\exp\left(-\frac{\mu}{\Omega}x^2\right) \]
+ *
+ * <p>for \( \mu > 0 \) the shape,
+ * \( \Omega > 0 \) the scale, and
+ * \( x \in (0, \infty) \).
*/
public final class NakagamiDistribution extends AbstractContinuousDistribution {
/** Support lower bound. */
diff --git a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/NormalDistribution.java b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/NormalDistribution.java
index 2848dd4..133d1fa 100644
--- a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/NormalDistribution.java
+++ b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/NormalDistribution.java
@@ -26,6 +26,14 @@ import org.apache.commons.rng.sampling.distribution.ZigguratSampler;
/**
* Implementation of the <a href="http://en.wikipedia.org/wiki/Normal_distribution">normal (Gaussian) distribution</a>.
+ *
+ * <p>The probability density function of \( X \) is:
+ *
+ * <p>\[ f(x; \mu, \sigma) = \frac 1 {\sigma\sqrt{2\pi}} e^{-{\frac 1 2}\left( \frac{x-\mu}{\sigma} \right)^2 } \]
+ *
+ * <p>for \( \mu \) the mean,
+ * \( \sigma > 0 \) the standard deviation, and
+ * \( x \in (-\infty, \infty) \).
*/
public final class NormalDistribution extends AbstractContinuousDistribution {
/** 0.5 * ln(2 * pi). Computed to 25-digits precision. */
diff --git a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/ParetoDistribution.java b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/ParetoDistribution.java
index c57b6a8..bc58ec7 100644
--- a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/ParetoDistribution.java
+++ b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/ParetoDistribution.java
@@ -28,7 +28,9 @@ import org.apache.commons.rng.sampling.distribution.InverseTransformParetoSample
*
* <p>\[ f(x; k, \alpha) = \frac{\alpha k^\alpha}{x^{\alpha + 1}} \]
*
- * <p>for \( k > 0 \), \( \alpha > 0 \), \( x \in [k, \infty) \).
+ * <p>for \( k > 0 \),
+ * \( \alpha > 0 \), and
+ * \( x \in [k, \infty) \).
*
* <p>\( k \) is a <em>scale</em> parameter: this is the minimum possible value of \( X \).
* <br>\( \alpha \) is a <em>shape</em> parameter: this is the Pareto index.
diff --git a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/PascalDistribution.java b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/PascalDistribution.java
index a66f363..40e31e5 100644
--- a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/PascalDistribution.java
+++ b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/PascalDistribution.java
@@ -23,28 +23,38 @@ import org.apache.commons.numbers.gamma.RegularizedBeta;
/**
* Implementation of the <a href="http://en.wikipedia.org/wiki/Negative_binomial_distribution">Pascal distribution.</a>
*
- * The Pascal distribution is a special case of the Negative Binomial distribution
+ * <p>The Pascal distribution is a special case of the Negative Binomial distribution
* where the number of successes parameter is an integer.
*
- * There are various ways to express the probability mass and distribution
+ * <p>There are various ways to express the probability mass and distribution
* functions for the Pascal distribution. The present implementation represents
- * the distribution of the number of failures before {@code r} successes occur.
+ * the distribution of the number of failures before \( r \) successes occur.
* This is the convention adopted in e.g.
* <a href="http://mathworld.wolfram.com/NegativeBinomialDistribution.html">MathWorld</a>,
* but <em>not</em> in
* <a href="http://en.wikipedia.org/wiki/Negative_binomial_distribution">Wikipedia</a>.
*
- * For a random variable {@code X} whose values are distributed according to this
- * distribution, the probability mass function is given by<br>
- * {@code P(X = k) = C(k + r - 1, r - 1) * p^r * (1 - p)^k,}<br>
- * where {@code r} is the number of successes, {@code p} is the probability of
- * success, and {@code X} is the total number of failures. {@code C(n, k)} is
- * the binomial coefficient ({@code n} choose {@code k}). The mean and variance
- * of {@code X} are<br>
- * {@code E(X) = (1 - p) * r / p, var(X) = (1 - p) * r / p^2.}<br>
- * Finally, the cumulative distribution function is given by<br>
- * {@code P(X <= k) = I(p, r, k + 1)},
- * where I is the regularized incomplete Beta function.
+ * <p>The probability mass function of \( X \) is:
+ *
+ * <p>\[ f(k; r, p) = \binom{k+r-1}{r-1} p^r \, (1-p)^k \]
+ *
+ * <p>for \( r \in \{1, 2, \dots\} \) the number of successes,
+ * \( p \in (0, 1] \) the probability of success,
+ * \( k \in \{0, 1, 2, \dots\} \) the total number of failures, and
+ *
+ * <p>\[ \binom{k+r-1}{r-1} = \frac{(k+r-1)!}{(r-1)! \, k!} \]
+ *
+ * <p>is the binomial coefficient.
+ *
+ * <p>The mean and variance of \( X \) are:
+ *
+ * <p>\[ \begin{aligned} \mathbb{E}(X) &= \frac {(1 - p) r}{p} \\ \mathrm{Var}(X) &= \frac {(1 - p) r}{p^2} \end{aligned} \]
+ *
+ * <p>The cumulative distribution function of \( X \) is:
+ *
+ * <p>\[ P(X \leq k) = I(p, r, k + 1) \]
+ *
+ * <p>where \( I \) is the regularized incomplete beta function.
*/
public final class PascalDistribution extends AbstractDiscreteDistribution {
/** The number of successes. */
diff --git a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/PoissonDistribution.java b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/PoissonDistribution.java
index f0c2295..85a2b1a 100644
--- a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/PoissonDistribution.java
+++ b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/PoissonDistribution.java
@@ -25,6 +25,13 @@ import org.apache.commons.rng.sampling.distribution.ZigguratSampler;
/**
* Implementation of the <a href="http://en.wikipedia.org/wiki/Poisson_distribution">Poisson distribution</a>.
+ *
+ * <p>The probability mass function of \( X \) is:
+ *
+ * <p>\[ f(k; \lambda) = \frac{\lambda^k e^{-k}}{k!} \]
+ *
+ * <p>for \( \lambda \in (0, \infty) \) the mean and
+ * \( k \in \{0, 1, 2, \dots\} \) the number of events.
*/
public final class PoissonDistribution extends AbstractDiscreteDistribution {
/** 0.5 * ln(2 * pi). Computed to 25-digits precision. */
diff --git a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/TDistribution.java b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/TDistribution.java
index beecfa7..0eeb1e5 100644
--- a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/TDistribution.java
+++ b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/TDistribution.java
@@ -22,6 +22,14 @@ import org.apache.commons.numbers.gamma.LogGamma;
/**
* Implementation of <a href='http://en.wikipedia.org/wiki/Student's_t-distribution'>Student's t-distribution</a>.
+ *
+ * <p>The probability density function of \( X \) is:
+ *
+ * <p>\[ f(x; v) = \frac{\Gamma(\frac{\nu+1}{2})} {\sqrt{\nu\pi}\,\Gamma(\frac{\nu}{2})} \left(1+\frac{t^2}{\nu} \right)^{\!-\frac{\nu+1}{2}} \]
+ *
+ * <p>for \( v > 0 \) the degrees of freedom,
+ * \( \Gamma \) is the gamma function, and
+ * \( x \in (-\infty, \infty) \).
*/
public abstract class TDistribution extends AbstractContinuousDistribution {
/** A standard normal distribution used for calculations.
diff --git a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/TriangularDistribution.java b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/TriangularDistribution.java
index 81ce547..baa18c2 100644
--- a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/TriangularDistribution.java
+++ b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/TriangularDistribution.java
@@ -18,7 +18,18 @@
package org.apache.commons.statistics.distribution;
/**
- * Implementation of the triangular real distribution.
+ * Implementation of the triangular distribution.
+ *
+ * <p>The probability density function of \( X \) is:
+ *
+ * <p>\[ f(x; a, b, c) = \begin{cases}
+ * \frac{2(x-a)}{(b-a)(c-a)} & \text{for } a \le x \lt c \\
+ * \frac{2}{b-a} & \text{for } x = c \\
+ * \frac{2(b-x)}{(b-a)(b-c)} & \text{for } c \lt x \le b \\
+ * \end{cases} \]
+ *
+ * <p>for \( -\infty \lt a \le c \le b \lt \infty \) and
+ * \( x \in [a, b] \).
*
* @see <a href="http://en.wikipedia.org/wiki/Triangular_distribution">
* Triangular distribution (Wikipedia)</a>
diff --git a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/TruncatedNormalDistribution.java b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/TruncatedNormalDistribution.java
index 1dec468..d36fac6 100644
--- a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/TruncatedNormalDistribution.java
+++ b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/TruncatedNormalDistribution.java
@@ -24,6 +24,17 @@ import org.apache.commons.numbers.gamma.Erfcx;
/**
* Implementation of the truncated normal distribution.
*
+ * <p>The probability density function of \( X \) is:
+ *
+ * <p>\[ f(x;\mu,\sigma,a,b) = \frac{1}{\sigma}\,\frac{\phi(\frac{x - \mu}{\sigma})}{\Phi(\frac{b - \mu}{\sigma}) - \Phi(\frac{a - \mu}{\sigma}) } \]
+ *
+ * <p>for \( \mu \) mean of the parent normal distribution,
+ * \( \sigma \) standard deviation of the parent normal distribution,
+ * \( -\infty \le a \lt b \le \infty \) the truncation interval, and
+ * \( x \in [a, b] \), where \( \phi \) is the probability
+ * density function of the standard normal distribution and \( \Phi \)
+ * is its cumulative distribution function.
+ *
* @see <a href="https://en.wikipedia.org/wiki/Truncated_normal_distribution">
* Truncated normal distribution (Wikipedia)</a>
*/
diff --git a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/UniformContinuousDistribution.java b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/UniformContinuousDistribution.java
index d9acb29..d7fccf6 100644
--- a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/UniformContinuousDistribution.java
+++ b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/UniformContinuousDistribution.java
@@ -22,6 +22,13 @@ import org.apache.commons.rng.sampling.distribution.ContinuousUniformSampler;
/**
* Implementation of the <a href="http://en.wikipedia.org/wiki/Uniform_distribution_(continuous)">uniform distribution</a>.
+ *
+ * <p>The probability density function of \( X \) is:
+ *
+ * <p>\[ f(x; a, b) = \frac{1}{b-a} \]
+ *
+ * <p>for \( -\infty \lt a \lt b \lt \infty \) and
+ * \( x \in [a, b] \).
*/
public final class UniformContinuousDistribution extends AbstractContinuousDistribution {
/** Lower bound of this distribution (inclusive). */
diff --git a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/UniformDiscreteDistribution.java b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/UniformDiscreteDistribution.java
index dbfad35..5624324 100644
--- a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/UniformDiscreteDistribution.java
+++ b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/UniformDiscreteDistribution.java
@@ -23,6 +23,13 @@ import org.apache.commons.rng.sampling.distribution.DiscreteUniformSampler;
/**
* Implementation of the <a href="http://en.wikipedia.org/wiki/Uniform_distribution_(discrete)">
* uniform integer distribution</a>.
+ *
+ * <p>The probability mass function of \( X \) is:
+ *
+ * <p>\[ f(k; a, b) = \frac{1}{b-a+1} \]
+ *
+ * <p>for integer \( a, b \) and \( a \le b \) and
+ * \( k \in [a, b] \).
*/
public final class UniformDiscreteDistribution extends AbstractDiscreteDistribution {
/** Lower bound (inclusive) of this distribution. */
diff --git a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/WeibullDistribution.java b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/WeibullDistribution.java
index a2de523..5ac33e7 100644
--- a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/WeibullDistribution.java
+++ b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/WeibullDistribution.java
@@ -22,15 +22,20 @@ import org.apache.commons.rng.UniformRandomProvider;
import org.apache.commons.rng.sampling.distribution.ZigguratSampler;
/**
- * Implementation of the Weibull distribution. This implementation uses the
- * two parameter form of the distribution defined by
- * <a href="http://mathworld.wolfram.com/WeibullDistribution.html">
- * Weibull Distribution</a>, equations (1) and (2).
+ * Implementation of the Weibull distribution.
+ *
+ * <p>The probability density function of \( X \) is:
+ *
+ * <p>\[ f(x;k,\lambda) = \frac{k}{\lambda}\left(\frac{x}{\lambda}\right)^{k-1}e^{-(x/\lambda)^{k}} \]
+ *
+ * <p>for \( k > 0 \) the shape,
+ * \( \lambda > 0 \) the scale, and
+ * \( x \in (0, \infty) \).
*
* <p>Note the special cases:
* <ul>
- * <li>{@code shape == 1} is the exponential distribution
- * <li>{@code shape == 2} is the Rayleigh distribution
+ * <li>\( k = 1 \) is the exponential distribution
+ * <li>\( k = 2 \) is the Rayleigh distribution with scale \( \sigma = \frac {\lambda}{\sqrt{2}} \)
* </ul>
*
* @see <a href="http://en.wikipedia.org/wiki/Weibull_distribution">Weibull distribution (Wikipedia)</a>
@@ -51,13 +56,13 @@ public final class WeibullDistribution extends AbstractContinuousDistribution {
private final double logShapeOverScale;
/**
- * @param alpha Shape parameter.
- * @param beta Scale parameter.
+ * @param shape Shape parameter.
+ * @param scale Scale parameter.
*/
- private WeibullDistribution(double alpha,
- double beta) {
- scale = beta;
- shape = alpha;
+ private WeibullDistribution(double shape,
+ double scale) {
+ this.scale = scale;
+ this.shape = shape;
shapeOverScale = shape / scale;
logShapeOverScale = Math.log(shapeOverScale);
}
@@ -65,22 +70,22 @@ public final class WeibullDistribution extends AbstractContinuousDistribution {
/**
* Creates a Weibull distribution.
*
- * @param alpha Shape parameter.
- * @param beta Scale parameter.
+ * @param shape Shape parameter.
+ * @param scale Scale parameter.
* @return the distribution
- * @throws IllegalArgumentException if {@code alpha <= 0} or {@code beta <= 0}.
+ * @throws IllegalArgumentException if {@code shape <= 0} or {@code scale <= 0}.
*/
- public static WeibullDistribution of(double alpha,
- double beta) {
- if (alpha <= 0) {
+ public static WeibullDistribution of(double shape,
+ double scale) {
+ if (shape <= 0) {
throw new DistributionException(DistributionException.NOT_STRICTLY_POSITIVE,
- alpha);
+ shape);
}
- if (beta <= 0) {
+ if (scale <= 0) {
throw new DistributionException(DistributionException.NOT_STRICTLY_POSITIVE,
- beta);
+ scale);
}
- return new WeibullDistribution(alpha, beta);
+ return new WeibullDistribution(shape, scale);
}
/**
diff --git a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/ZipfDistribution.java b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/ZipfDistribution.java
index 1ca8b2d..0a2f26c 100644
--- a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/ZipfDistribution.java
+++ b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/ZipfDistribution.java
@@ -23,19 +23,17 @@ import org.apache.commons.rng.sampling.distribution.RejectionInversionZipfSample
/**
* Implementation of the <a href="https://en.wikipedia.org/wiki/Zipf's_law">Zipf distribution</a>.
- * <p>
- * <strong>Parameters:</strong>
- * For a random variable {@code X} whose values are distributed according to this
- * distribution, the probability mass function is given by:
- * <pre>
- * P(X = k) = H(N,s) * 1 / k^s for {@code k = 1,2,...,N}.
- * </pre>
- * <p>{@code H(N,s)} is the normalizing constant
- * which corresponds to the generalized harmonic number of order N of s.
- * <ul>
- * <li>{@code N} is the number of elements</li>
- * <li>{@code s} is the exponent</li>
- * </ul>
+ *
+ * <p>The probability mass function of \( X \) is:
+ *
+ * <p>\[ f(k; N, s) = \frac{1/k^s}{H_{N,s}} \]
+ *
+ * <p>for \( N \in \{1, 2, 3, \dots\} \) the number of elements,
+ * \( s \gt 0 \) the exponent characterizing the distribution,
+ * \( k \in \{1, 2, \dots, N\} \) the element rank, and
+ * \( H_{N,s} \) is the normalizing constant which corresponds to the
+ * <a href="https://en.wikipedia.org/wiki/Harmonic_number#Generalized_harmonic_numbers">
+ * generalized harmonic number</a> of order N of s.
*/
public final class ZipfDistribution extends AbstractDiscreteDistribution {
/** Number of elements. */