From 35fa22ed957039b16d64647a6b5d19c1d9892d2b Mon Sep 17 00:00:00 2001 From: Mikkel Meyer Andersen Date: Mon, 21 Mar 2011 13:02:34 +0000 Subject: [PATCH] (Too) poor javadoc for MATH-437 improved git-svn-id: https://svn.apache.org/repos/asf/commons/proper/math/trunk@1083767 13f79535-47bb-0310-9956-ffa450edef68 --- .../KolmogorovSmirnovDistribution.java | 36 ++----- .../KolmogorovSmirnovDistributionImpl.java | 97 +++++++++++++------ 2 files changed, 80 insertions(+), 53 deletions(-) diff --git a/src/main/java/org/apache/commons/math/distribution/KolmogorovSmirnovDistribution.java b/src/main/java/org/apache/commons/math/distribution/KolmogorovSmirnovDistribution.java index 7800ba35d..baaa70e33 100644 --- a/src/main/java/org/apache/commons/math/distribution/KolmogorovSmirnovDistribution.java +++ b/src/main/java/org/apache/commons/math/distribution/KolmogorovSmirnovDistribution.java @@ -17,40 +17,24 @@ package org.apache.commons.math.distribution; +import org.apache.commons.math.exception.MathArithmeticException; + /** * Treats the distribution of the two-sided - * {@code P(Dn < d)} - * where {@code Dn = sup_x | G(x) - Gn (x) |} for the + * {@code P(D}{@code n}{@code < d)} + * where {@code D}{@code n}{@code = sup_x | G(x) - Gn (x) |} for the * theoretical cdf G and the emperical cdf Gn. * - * This implementation is based on [1] with certain quick - * decisions for extreme values given in [2]. - * - * In short, when wanting to evaluate {@code P(Dn < d)}, - * the method in [1] is to write {@code d = (k - h) / n} for positive - * integer {@code k} and {@code 0 <= h < 1}. Then - * {@code P(Dn < d) = (n!/n^n) * t_kk} - * where {@code t_kk} is the (k, k)'th entry in the special matrix {@code H^n}, - * i.e. {@code H} to the {@code n}'th power. - * - * See also - * Kolmogorov-Smirnov test on Wikipedia for details. - * - * References: - * [1] Evaluating Kolmogorov's Distribution by George Marsaglia, Wai - * Wan Tsang, Jingbo Wang http://www.jstatsoft.org/v08/i18/paper - * - * [2] - * Computing the Two-Sided Kolmogorov-Smirnov Distribution by Richard Simard - * and Pierre L'Ecuyer - * - * Note that [1] contains an error in computing h, refer to - * MATH-437 for details. - * * @version $Revision$ $Date$ */ public interface KolmogorovSmirnovDistribution { + /** + * Calculates {@code P(D}n {@code < d)}. + * + * @param d statistic + * @return the two-sided probability of {@code P(D}n {@code < d)} + */ public double cdf(double d); } diff --git a/src/main/java/org/apache/commons/math/distribution/KolmogorovSmirnovDistributionImpl.java b/src/main/java/org/apache/commons/math/distribution/KolmogorovSmirnovDistributionImpl.java index b72029cff..6d12b9969 100644 --- a/src/main/java/org/apache/commons/math/distribution/KolmogorovSmirnovDistributionImpl.java +++ b/src/main/java/org/apache/commons/math/distribution/KolmogorovSmirnovDistributionImpl.java @@ -33,6 +33,37 @@ import org.apache.commons.math.linear.RealMatrix; /** * The default implementation of {@link KolmogorovSmirnovDistribution}. * + *

Treats the distribution of the two-sided + * {@code P(D}{@code n}{@code < d)} + * where {@code D}{@code n}{@code = sup_x | G(x) - Gn (x) |} for the + * theoretical cdf G and the emperical cdf Gn.

+ * + *

This implementation is based on [1] with certain quick + * decisions for extreme values given in [2].

+ * + *

In short, when wanting to evaluate {@code P(D}{@code n}{@code < d)}, + * the method in [1] is to write {@code d = (k - h) / n} for positive + * integer {@code k} and {@code 0 <= h < 1}. Then + * {@code P(D}{@code n}{@code < d) = (n!/n}{@code n}{@code ) * t_kk} + * where {@code t_kk} is the {@code (k, k)}'th entry in the special + * matrix {@code H}{@code n}, i.e. {@code H} to the {@code n}'th power.

+ * + *

See also + * Kolmogorov-Smirnov test on Wikipedia for details.

+ * + *

References: + *

+ * Note that [1] contains an error in computing h, refer to + * MATH-437 for details. + *

+ * * @version $Revision$ $Date$ */ public class KolmogorovSmirnovDistributionImpl implements KolmogorovSmirnovDistribution, Serializable { @@ -45,7 +76,7 @@ public class KolmogorovSmirnovDistributionImpl implements KolmogorovSmirnovDistr /** * @param n Number of observations * @throws NotStrictlyPositiveException - * if n <= 0 + * if {@code n <= 0} */ public KolmogorovSmirnovDistributionImpl(int n) { if (n <= 0) { @@ -56,7 +87,7 @@ public class KolmogorovSmirnovDistributionImpl implements KolmogorovSmirnovDistr } /** - * Calculates {@code P(Dn < d)} using method described in + * Calculates {@code P(D}n {@code < d)} using method described in * [1] with quick decisions for extreme values given in [2] (see above). The * result is not exact as with * {@link KolmogorovSmirnovDistributionImpl#cdfExact(double)} because @@ -64,17 +95,19 @@ public class KolmogorovSmirnovDistributionImpl implements KolmogorovSmirnovDistr * {@link org.apache.commons.math.fraction.BigFraction}. * * @param d statistic - * @return the two-sided probability of {@code P(Dn < d)} + * @return the two-sided probability of {@code P(D}n {@code < d)} * @throws MathArithmeticException - * if algorithm fails to convert h to a BigFraction in - * expressing d as (k - h) / m for integer k, m and 0 <= h < 1. + * if algorithm fails to convert {@code h} to a + * {@link org.apache.commons.math.fraction.BigFraction} in + * expressing {@code d} as {@code (k - h) / m} for integer + * {@code k, m} and {@code 0 <= h < 1}. */ public double cdf(double d) throws MathArithmeticException { return this.cdf(d, false); } /** - * Calculates {@code P(Dn < d)} using method described in + * Calculates {@code P(D}n {@code < d)} using method described in * [1] with quick decisions for extreme values given in [2] (see above). * The result is exact in the sense that BigFraction/BigReal is used everywhere * at the expense of very slow execution time. Almost never choose this in @@ -83,17 +116,19 @@ public class KolmogorovSmirnovDistributionImpl implements KolmogorovSmirnovDistr * {@link KolmogorovSmirnovDistributionImpl#cdf(double)} * * @param d statistic - * @return the two-sided probability of {@code P(Dn < d)} + * @return the two-sided probability of {@code P(D}n {@code < d)} * @throws MathArithmeticException - * if algorithm fails to convert h to a BigFraction in - * expressing d as (k - h) / m for integer k, m and 0 <= h < 1. + * if algorithm fails to convert {@code h} to a + * {@link org.apache.commons.math.fraction.BigFraction} in + * expressing {@code d} as {@code (k - h) / m} for integer + * {@code k, m} and {@code 0 <= h < 1}. */ public double cdfExact(double d) throws MathArithmeticException { return this.cdf(d, true); } /** - * Calculates {@code P(Dn < d)} using method described in + * Calculates {@code P(D}n {@code < d)} using method described in * [1] with quick decisions for extreme values given in [2] (see above). * * @param d statistic @@ -101,13 +136,15 @@ public class KolmogorovSmirnovDistributionImpl implements KolmogorovSmirnovDistr * whether the probability should be calculated exact using * BigFraction everywhere at the expense of very * slow execution time, or if double should be used convenient - * places to gain speed. Never choose true in real applications - * unless you are very sure; true is almost solely for - * verification purposes. - * @return the two-sided probability of {@code P(Dn < d)} + * places to gain speed. Almost never choose {@code true} in + * real applications unless you are very sure; {@code true} is + * almost solely for verification purposes. + * @return the two-sided probability of {@code P(D}n {@code < d)} * @throws MathArithmeticException - * if algorithm fails to convert h to a BigFraction in - * expressing d as (k - h) / m for integer k, m and 0 <= h < 1. + * if algorithm fails to convert {@code h} to a + * {@link org.apache.commons.math.fraction.BigFraction} in + * expressing {@code d} as {@code (k - h) / m} for integer + * {@code k, m} and {@code 0 <= h < 1}. */ public double cdf(double d, boolean exact) throws MathArithmeticException { @@ -146,14 +183,16 @@ public class KolmogorovSmirnovDistributionImpl implements KolmogorovSmirnovDistr } /** - * Calculates {@code P(Dn < d)} exact using method + * Calculates {@code P(D}n {@code < d)} exact using method * described in [1] and BigFraction (see above). * * @param d statistic - * @return the two-sided probability of {@code P(Dn < d)} + * @return the two-sided probability of {@code P(D}n {@code < d)} * @throws MathArithmeticException - * if algorithm fails to convert h to a BigFraction in - * expressing d as (k - h) / m for integer k, m and 0 <= h < 1. + * if algorithm fails to convert {@code h} to a + * {@link org.apache.commons.math.fraction.BigFraction} in + * expressing {@code d} as {@code (k - h) / m} for integer + * {@code k, m} and {@code 0 <= h < 1}. */ private double exactK(double d) throws MathArithmeticException { @@ -180,14 +219,16 @@ public class KolmogorovSmirnovDistributionImpl implements KolmogorovSmirnovDistr } /** - * Calculates P(Dn < d) using method described in + * Calculates {@code P(D}n {@code < d)} using method described in * [1] and doubles (see above). * * @param d statistic - * @return the two-sided probability of {@code P(Dn < d)} + * @return the two-sided probability of {@code P(D}n {@code < d)} * @throws MathArithmeticException - * if algorithm fails to convert h to a BigFraction in - * expressing d as (k - h) / m for integer k, m and 0 <= h < 1. + * if algorithm fails to convert {@code h} to a + * {@link org.apache.commons.math.fraction.BigFraction} in + * expressing {@code d} as {@code (k - h) / m} for integer + * {@code k, m} and {@code 0 <= h < 1}. */ private double roundedK(double d) throws MathArithmeticException { @@ -221,13 +262,15 @@ public class KolmogorovSmirnovDistributionImpl implements KolmogorovSmirnovDistr } /*** - * Creates H of size m x m as described in [1] (see above). + * Creates {@code H} of size {@code m x m} as described in [1] (see above). * * @param d statistic * * @throws MathArithmeticException - * if algorithm fails to convert h to a BigFraction in - * expressing x as (k - h) / m for integer k, m and 0 <= h < 1. + * if algorithm fails to convert {@code h} to a + * {@link org.apache.commons.math.fraction.BigFraction} in + * expressing {@code d} as {@code (k - h) / m} for integer + * {@code k, m} and {@code 0 <= h < 1}. */ private FieldMatrix createH(double d) throws MathArithmeticException {