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 <[email protected]> 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. */
