Apache
/
commons-math
mirror of https://github.com/apache/commons-math.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

(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
This commit is contained in:
Mikkel Meyer Andersen 2011-03-21 13:02:34 +00:00
parent ba9b83410c
commit 35fa22ed95
2 changed files with 80 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
src/main/java/org/apache/commons/math/distribution/KolmogorovSmirnovDistribution.java
View File

@ -17,40 +17,24 @@
package org.apache.commons.math.distribution; package org.apache.commons.math.distribution;
import org.apache.commons.math.exception.MathArithmeticException;
/** /**
* Treats the distribution of the two-sided * Treats the distribution of the two-sided
* {@code P(D<sub>n</sup> &lt; d)} * {@code P(D}<sub>{@code n}</sub>{@code < d)}
* where {@code D<sub>n</sup> = sup_x | G(x) - Gn (x) |} for the * where {@code D}<sub>{@code n}</sub>{@code = sup_x | G(x) - Gn (x) |} for the
* theoretical cdf G and the emperical cdf Gn. * 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<sub>n</sup> &lt; 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<sub>n</sup> &lt; 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 <a href="http://en.wikipedia.org/wiki/Kolmogorov-Smirnov_test">
* Kolmogorov-Smirnov test on Wikipedia</a> for details.
*
* References:
* [1] Evaluating Kolmogorov's Distribution by George Marsaglia, Wai
* Wan Tsang, Jingbo Wang http://www.jstatsoft.org/v08/i18/paper
*
* [2] <a href="http://www.iro.umontreal.ca/~lecuyer/myftp/papers/ksdist.pdf">
* Computing the Two-Sided Kolmogorov-Smirnov Distribution</a> by Richard Simard
* and Pierre L'Ecuyer
*
* Note that [1] contains an error in computing h, refer to
* <a href="https://issues.apache.org/jira/browse/MATH-437">MATH-437</a> for details.
*
* @version $Revision$ $Date$ * @version $Revision$ $Date$
*/ */
public interface KolmogorovSmirnovDistribution { public interface KolmogorovSmirnovDistribution {
/**
* Calculates {@code P(D}<sub>n</sub> {@code < d)}.
*
* @param d statistic
* @return the two-sided probability of {@code P(D}<sub>n</sub> {@code < d)}
*/
public double cdf(double d); public double cdf(double d);
} }

97
src/main/java/org/apache/commons/math/distribution/KolmogorovSmirnovDistributionImpl.java
View File

@ -33,6 +33,37 @@ import org.apache.commons.math.linear.RealMatrix;
/** /**
* The default implementation of {@link KolmogorovSmirnovDistribution}. * The default implementation of {@link KolmogorovSmirnovDistribution}.
* *
* <p>Treats the distribution of the two-sided
* {@code P(D}<sub>{@code n}</sub>{@code < d)}
* where {@code D}<sub>{@code n}</sub>{@code = sup_x | G(x) - Gn (x) |} for the
* theoretical cdf G and the emperical cdf Gn.</p>
*
* <p>This implementation is based on [1] with certain quick
* decisions for extreme values given in [2].</p>
*
* <p>In short, when wanting to evaluate {@code P(D}<sub>{@code n}</sub>{@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}<sub>{@code n}</sub>{@code < d) = (n!/n}<sup>{@code n}</sup>{@code ) * t_kk}
* where {@code t_kk} is the {@code (k, k)}'th entry in the special
* matrix {@code H}<sup>{@code n}</sup>, i.e. {@code H} to the {@code n}'th power.</p>
*
* <p>See also <a href="http://en.wikipedia.org/wiki/Kolmogorov-Smirnov_test">
* Kolmogorov-Smirnov test on Wikipedia</a> for details.</p>
*
* <p>References:
* <ul>
* <li>[1] <a href="http://www.jstatsoft.org/v08/i18/paper">
* Evaluating Kolmogorov's Distribution</a> by George Marsaglia, Wai
* Wan Tsang, and Jingbo Wang</li>
* <li>[2] <a href="http://www.iro.umontreal.ca/~lecuyer/myftp/papers/ksdist.pdf">
* Computing the Two-Sided Kolmogorov-Smirnov Distribution</a> by Richard Simard
* and Pierre L'Ecuyer</li>
* </ul>
* Note that [1] contains an error in computing h, refer to
* <a href="https://issues.apache.org/jira/browse/MATH-437">MATH-437</a> for details.
* </p>
*
* @version $Revision$ $Date$ * @version $Revision$ $Date$
*/ */
public class KolmogorovSmirnovDistributionImpl implements KolmogorovSmirnovDistribution, Serializable { public class KolmogorovSmirnovDistributionImpl implements KolmogorovSmirnovDistribution, Serializable {
@ -45,7 +76,7 @@ public class KolmogorovSmirnovDistributionImpl implements KolmogorovSmirnovDistr
/** /**
* @param n Number of observations * @param n Number of observations
* @throws NotStrictlyPositiveException * @throws NotStrictlyPositiveException
* if n <= 0 * if {@code n <= 0}
*/ */
public KolmogorovSmirnovDistributionImpl(int n) { public KolmogorovSmirnovDistributionImpl(int n) {
if (n <= 0) { if (n <= 0) {
@ -56,7 +87,7 @@ public class KolmogorovSmirnovDistributionImpl implements KolmogorovSmirnovDistr
} }
/** /**
* Calculates {@code P(D<sub>n</sup> &lt; d)} using method described in * Calculates {@code P(D}<sub>n</sub> {@code < d)} using method described in
* [1] with quick decisions for extreme values given in [2] (see above). The * [1] with quick decisions for extreme values given in [2] (see above). The
* result is not exact as with * result is not exact as with
* {@link KolmogorovSmirnovDistributionImpl#cdfExact(double)} because * {@link KolmogorovSmirnovDistributionImpl#cdfExact(double)} because
@ -64,17 +95,19 @@ public class KolmogorovSmirnovDistributionImpl implements KolmogorovSmirnovDistr
* {@link org.apache.commons.math.fraction.BigFraction}. * {@link org.apache.commons.math.fraction.BigFraction}.
* *
* @param d statistic * @param d statistic
* @return the two-sided probability of {@code P(D<sub>n</sup> &lt; d)} * @return the two-sided probability of {@code P(D}<sub>n</sub> {@code < d)}
* @throws MathArithmeticException * @throws MathArithmeticException
* if algorithm fails to convert h to a BigFraction in * if algorithm fails to convert {@code h} to a
* expressing d as (k - h) / m for integer k, m and 0 <= h < 1. * {@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 { public double cdf(double d) throws MathArithmeticException {
return this.cdf(d, false); return this.cdf(d, false);
} }
/** /**
* Calculates {@code P(D<sub>n</sup> &lt; d)} using method described in * Calculates {@code P(D}<sub>n</sub> {@code < d)} using method described in
* [1] with quick decisions for extreme values given in [2] (see above). * [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 * 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 * 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)} * {@link KolmogorovSmirnovDistributionImpl#cdf(double)}
* *
* @param d statistic * @param d statistic
* @return the two-sided probability of {@code P(D<sub>n</sup> &lt; d)} * @return the two-sided probability of {@code P(D}<sub>n</sub> {@code < d)}
* @throws MathArithmeticException * @throws MathArithmeticException
* if algorithm fails to convert h to a BigFraction in * if algorithm fails to convert {@code h} to a
* expressing d as (k - h) / m for integer k, m and 0 <= h < 1. * {@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 { public double cdfExact(double d) throws MathArithmeticException {
return this.cdf(d, true); return this.cdf(d, true);
} }
/** /**
* Calculates {@code P(D<sub>n</sup> &lt; d)} using method described in * Calculates {@code P(D}<sub>n</sub> {@code < d)} using method described in
* [1] with quick decisions for extreme values given in [2] (see above). * [1] with quick decisions for extreme values given in [2] (see above).
* *
* @param d statistic * @param d statistic
@ -101,13 +136,15 @@ public class KolmogorovSmirnovDistributionImpl implements KolmogorovSmirnovDistr
* whether the probability should be calculated exact using * whether the probability should be calculated exact using
* BigFraction everywhere at the expense of very * BigFraction everywhere at the expense of very
* slow execution time, or if double should be used convenient * slow execution time, or if double should be used convenient
* places to gain speed. Never choose true in real applications * places to gain speed. Almost never choose {@code true} in
* unless you are very sure; true is almost solely for * real applications unless you are very sure; {@code true} is
* verification purposes. * almost solely for verification purposes.
* @return the two-sided probability of {@code P(D<sub>n</sup> &lt; d)} * @return the two-sided probability of {@code P(D}<sub>n</sub> {@code < d)}
* @throws MathArithmeticException * @throws MathArithmeticException
* if algorithm fails to convert h to a BigFraction in * if algorithm fails to convert {@code h} to a
* expressing d as (k - h) / m for integer k, m and 0 <= h < 1. * {@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) public double cdf(double d, boolean exact)
throws MathArithmeticException { throws MathArithmeticException {
@ -146,14 +183,16 @@ public class KolmogorovSmirnovDistributionImpl implements KolmogorovSmirnovDistr
} }
/** /**
* Calculates {@code P(D<sub>n</sup> &lt; d)} exact using method * Calculates {@code P(D}<sub>n</sub> {@code < d)} exact using method
* described in [1] and BigFraction (see above). * described in [1] and BigFraction (see above).
* *
* @param d statistic * @param d statistic
* @return the two-sided probability of {@code P(D<sub>n</sup> &lt; d)} * @return the two-sided probability of {@code P(D}<sub>n</sub> {@code < d)}
* @throws MathArithmeticException * @throws MathArithmeticException
* if algorithm fails to convert h to a BigFraction in * if algorithm fails to convert {@code h} to a
* expressing d as (k - h) / m for integer k, m and 0 <= h < 1. * {@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) private double exactK(double d)
throws MathArithmeticException { throws MathArithmeticException {
@ -180,14 +219,16 @@ public class KolmogorovSmirnovDistributionImpl implements KolmogorovSmirnovDistr
} }
/** /**
* Calculates <code>P(D<sub>n</sup> &lt; d)</code> using method described in * Calculates {@code P(D}<sub>n</sub> {@code < d)} using method described in
* [1] and doubles (see above). * [1] and doubles (see above).
* *
* @param d statistic * @param d statistic
* @return the two-sided probability of {@code P(D<sub>n</sup> &lt; d)} * @return the two-sided probability of {@code P(D}<sub>n</sub> {@code < d)}
* @throws MathArithmeticException * @throws MathArithmeticException
* if algorithm fails to convert h to a BigFraction in * if algorithm fails to convert {@code h} to a
* expressing d as (k - h) / m for integer k, m and 0 <= h < 1. * {@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) private double roundedK(double d)
throws MathArithmeticException { 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 * @param d statistic
* *
* @throws MathArithmeticException * @throws MathArithmeticException
* if algorithm fails to convert h to a BigFraction in * if algorithm fails to convert {@code h} to a
* expressing x as (k - h) / m for integer k, m and 0 <= h < 1. * {@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<BigFraction> createH(double d) private FieldMatrix<BigFraction> createH(double d)
throws MathArithmeticException { throws MathArithmeticException {