From 45a605897eb862d4561627e8963ed57b3b0849ae Mon Sep 17 00:00:00 2001 From: "Mark R. Diggory" Date: Tue, 15 Jul 2003 03:37:11 +0000 Subject: [PATCH] minor javadoc cleanup git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/math/trunk@140985 13f79535-47bb-0310-9956-ffa450edef68 --- .../AbstractStorelessUnivariateStatistic.java | 7 ++- .../AbstractUnivariateStatistic.java | 20 +++++--- .../StorelessUnivariateStatistic.java | 22 +++++---- .../stat/univariate/UnivariateStatistic.java | 13 +++-- .../stat/univariate/moment/FirstMoment.java | 48 ++++++++++++------- .../math/stat/univariate/moment/Mean.java | 11 +++-- .../math/stat/univariate/moment/Variance.java | 23 ++++----- .../commons/math/stat/univariate/package.html | 35 ++++++++++++++ .../math/stat/univariate/summary/Sum.java | 13 +++-- 9 files changed, 126 insertions(+), 66 deletions(-) create mode 100644 src/java/org/apache/commons/math/stat/univariate/package.html diff --git a/src/java/org/apache/commons/math/stat/univariate/AbstractStorelessUnivariateStatistic.java b/src/java/org/apache/commons/math/stat/univariate/AbstractStorelessUnivariateStatistic.java index c7b5715ff..82033f676 100644 --- a/src/java/org/apache/commons/math/stat/univariate/AbstractStorelessUnivariateStatistic.java +++ b/src/java/org/apache/commons/math/stat/univariate/AbstractStorelessUnivariateStatistic.java @@ -59,7 +59,7 @@ package org.apache.commons.math.stat.univariate; * Provides the ability to extend polymophically so that * indiviual statistics do not need to implement these methods unless * there are better algorithms for handling the calculation. - * @version $Revision: 1.4 $ $Date: 2003/07/09 20:04:13 $ + * @version $Revision: 1.5 $ $Date: 2003/07/15 03:37:10 $ */ public abstract class AbstractStorelessUnivariateStatistic extends AbstractUnivariateStatistic @@ -70,15 +70,18 @@ public abstract class AbstractStorelessUnivariateStatistic * calculation off to the instantanious increment method. In most cases of * StorelessUnivariateStatistic this is never really used because more * efficient algorithms are available for that statistic. - * @see org.apache.commons.math.stat.univariate.UnivariateStatistic#evaluate(double[], int, int) + * @see org.apache.commons.math.stat.univariate. + * UnivariateStatistic#evaluate(double[], int, int) */ public double evaluate(double[] values, int begin, int length) { if (this.test(values, begin, length)) { this.clear(); + int l = begin + length; for (int i = begin; i < begin + length; i++) { increment(values[i]); } } return getResult(); } + } \ No newline at end of file diff --git a/src/java/org/apache/commons/math/stat/univariate/AbstractUnivariateStatistic.java b/src/java/org/apache/commons/math/stat/univariate/AbstractUnivariateStatistic.java index 0b16a6f65..aee6b5ab5 100644 --- a/src/java/org/apache/commons/math/stat/univariate/AbstractUnivariateStatistic.java +++ b/src/java/org/apache/commons/math/stat/univariate/AbstractUnivariateStatistic.java @@ -57,7 +57,7 @@ package org.apache.commons.math.stat.univariate; * Abstract Implementation for UnivariateStatistics. * Provides the ability to extend polymophically so that * indiviual statistics do not need to implement these methods. - * @version $Revision: 1.4 $ $Date: 2003/07/09 20:04:13 $ + * @version $Revision: 1.5 $ $Date: 2003/07/15 03:37:10 $ */ public abstract class AbstractUnivariateStatistic implements UnivariateStatistic { @@ -66,7 +66,8 @@ public abstract class AbstractUnivariateStatistic * This implementation provides a simple wrapper around the double[] * and passes the request onto the evaluate(DoubleArray da) method. * - * @see org.apache.commons.math.stat.univariate.UnivariateStatistic#evaluate(double[]) + * @see org.apache.commons.math.stat.univariate. + * UnivariateStatistic#evaluate(double[]) */ public double evaluate(double[] values) { return evaluate(values, 0, values.length); @@ -74,7 +75,8 @@ public abstract class AbstractUnivariateStatistic /** * Subclasses of AbstractUnivariateStatistc need to implement this method. - * @see org.apache.commons.math.stat.univariate.UnivariateStatistic#evaluate(double[], int, int) + * @see org.apache.commons.math.stat.univariate. + * UnivariateStatistic#evaluate(double[], int, int) */ public abstract double evaluate(double[] values, int begin, int length); @@ -87,17 +89,21 @@ public abstract class AbstractUnivariateStatistic */ protected boolean test(double[] values, int begin, int length) { - if (length > values.length) + if (length > values.length) { throw new IllegalArgumentException("length > values.length"); + } - if (begin + length > values.length) + if (begin + length > values.length) { throw new IllegalArgumentException("begin + length > values.length"); + } - if (values == null) + if (values == null) { throw new IllegalArgumentException("input value array is null"); + } - if (values.length == 0 || length == 0) + if (values.length == 0 || length == 0) { return false; + } return true; diff --git a/src/java/org/apache/commons/math/stat/univariate/StorelessUnivariateStatistic.java b/src/java/org/apache/commons/math/stat/univariate/StorelessUnivariateStatistic.java index b866934e2..97e60d674 100644 --- a/src/java/org/apache/commons/math/stat/univariate/StorelessUnivariateStatistic.java +++ b/src/java/org/apache/commons/math/stat/univariate/StorelessUnivariateStatistic.java @@ -54,13 +54,15 @@ package org.apache.commons.math.stat.univariate; /** - * StorelessUnivariate interface provides methods to increment and access - * the internal state of the Statistic. A StorelessUnivariateStatistic does - * not require that a double[] storage structure be maintained with the values - * in it. As such only a subset of known statistics can actually be implmented - * using it. If a Statistic cannot be implemented in a Storeless approach it - * should implement the UnivariateStatistic interface directly instead. - * @version $Revision: 1.5 $ $Date: 2003/07/09 20:04:13 $ + * Extends the capabilities of UnivariateStatistic with a statefull incremental + * strategy through three methods for calculating a statistic without having to + * maintain a double[] of the values. Because a StorelessUnivariateStatistic + * does not require that a double[] storage structure be maintained with the + * values in it, there are only a subset of known statistics can actually be + * implemented using it. If a Statistic cannot be implemented in a Storeless + * approach it should implement the UnivariateStatistic interface directly + * instead. + * @version $Revision: 1.6 $ $Date: 2003/07/15 03:37:10 $ */ public interface StorelessUnivariateStatistic extends UnivariateStatistic { @@ -69,7 +71,7 @@ public interface StorelessUnivariateStatistic extends UnivariateStatistic { * Implementation. * @param d is the value to increment the state by. */ - public void increment(double d); + void increment(double d); /** * Returns the current state of the statistic after the @@ -77,12 +79,12 @@ public interface StorelessUnivariateStatistic extends UnivariateStatistic { * @return value of the statistic, Double.NaN if it * has been cleared or just instantiated. */ - public double getResult(); + double getResult(); /** * Clears all the internal state of the Statistic */ - public void clear(); + void clear(); } \ No newline at end of file diff --git a/src/java/org/apache/commons/math/stat/univariate/UnivariateStatistic.java b/src/java/org/apache/commons/math/stat/univariate/UnivariateStatistic.java index 973ab1536..f7cded466 100644 --- a/src/java/org/apache/commons/math/stat/univariate/UnivariateStatistic.java +++ b/src/java/org/apache/commons/math/stat/univariate/UnivariateStatistic.java @@ -55,8 +55,10 @@ package org.apache.commons.math.stat.univariate; /** * UnivariateStatistic interface provides methods to evaluate - * double[] based content using a particular algorithm. - * @version $Revision: 1.4 $ $Date: 2003/07/09 20:04:13 $ + * double[] based content using an implemented statistical approach. + * The interface provides two "stateless" simple methods to calculate + * a statistic from a double[] based parameter. + * @version $Revision: 1.5 $ $Date: 2003/07/15 03:37:10 $ */ public interface UnivariateStatistic { @@ -66,16 +68,17 @@ public interface UnivariateStatistic { * @return the result of the evaluation or Double.NaN * if the array is empty */ - public double evaluate(double[] values); + double evaluate(double[] values); /** - * Evaluates part of a double[] returning the result of the evaluation. + * Evaluates part of a double[] returning the result + * of the evaluation. * @param values Is a double[] containing the values * @param begin processing at this point in the array * @param length processing at this point in the array * @return the result of the evaluation or Double.NaN * if the array is empty */ - public double evaluate(double[] values, int begin, int length); + double evaluate(double[] values, int begin, int length); } \ No newline at end of file diff --git a/src/java/org/apache/commons/math/stat/univariate/moment/FirstMoment.java b/src/java/org/apache/commons/math/stat/univariate/moment/FirstMoment.java index 25a445a54..e1b9e957e 100644 --- a/src/java/org/apache/commons/math/stat/univariate/moment/FirstMoment.java +++ b/src/java/org/apache/commons/math/stat/univariate/moment/FirstMoment.java @@ -62,7 +62,7 @@ import org.apache.commons.math.stat.univariate.AbstractStorelessUnivariateStatis * * recursive strategy * . Both incremental and evaluation strategies currently use this approach. - * @version $Revision: 1.4 $ $Date: 2003/07/09 20:04:10 $ + * @version $Revision: 1.5 $ $Date: 2003/07/15 03:36:36 $ */ public class FirstMoment extends AbstractStorelessUnivariateStatistic { @@ -71,45 +71,57 @@ public class FirstMoment extends AbstractStorelessUnivariateStatistic { /** first moment of values that have been added */ protected double m1 = Double.NaN; - - /** temporary internal state made available for higher order moments */ + + /** + * temporary internal state made available for + * higher order moments + */ protected double dev = 0.0; - - /** temporary internal state made available for higher order moments */ + + /** + * temporary internal state made available for + * higher order moments + */ protected double v = 0.0; - - /** temporary internal state made available for higher order moments */ + + /** + * temporary internal state made available for + * higher order moments + */ protected double n0 = 0.0; - + /** - * @see org.apache.commons.math.stat.univariate.StorelessUnivariateStatistic#increment(double) + * @see org.apache.commons.math.stat.univariate. + * StorelessUnivariateStatistic#increment(double) */ public void increment(double d) { if (n < 1) { - m1 = 0.0; + m1 = 0.0; } - + n++; dev = d - m1; - n0 = (double)n; + n0 = (double) n; v = dev / n0; - m1 += v; + m1 += v; } - + /** - * @see org.apache.commons.math.stat.univariate.StorelessUnivariateStatistic#clear() + * @see org.apache.commons.math.stat.univariate. + * StorelessUnivariateStatistic#clear() */ public void clear() { m1 = Double.NaN; n = 0; dev = 0.0; v = 0.0; - n0 = 0.0; + n0 = 0.0; } - + /** - * @see org.apache.commons.math.stat.univariate.StorelessUnivariateStatistic#getValue() + * @see org.apache.commons.math.stat.univariate. + * StorelessUnivariateStatistic#getValue() */ public double getResult() { return m1; diff --git a/src/java/org/apache/commons/math/stat/univariate/moment/Mean.java b/src/java/org/apache/commons/math/stat/univariate/moment/Mean.java index 2f226b975..461ffc847 100644 --- a/src/java/org/apache/commons/math/stat/univariate/moment/Mean.java +++ b/src/java/org/apache/commons/math/stat/univariate/moment/Mean.java @@ -53,14 +53,15 @@ */ package org.apache.commons.math.stat.univariate.moment; +import org.apache.commons.math.stat.univariate.AbstractStorelessUnivariateStatistic; import org.apache.commons.math.stat.univariate.summary.Sum; /** * Returns the * arithmetic mean of the available values. - * @version $Revision: 1.6 $ $Date: 2003/07/09 20:04:10 $ + * @version $Revision: 1.7 $ $Date: 2003/07/15 03:36:36 $ */ -public class Mean extends Sum { +public class Mean extends AbstractStorelessUnivariateStatistic { /** first moment of values that have been added */ protected FirstMoment moment = null; @@ -100,6 +101,9 @@ public class Mean extends Sum { public double getResult() { return moment.m1; } + + /*UnvariateStatistic Approach */ + Sum sum = new Sum(); /** * Returns the @@ -112,9 +116,8 @@ public class Mean extends Sum { */ public double evaluate(double[] values, int begin, int length) { if (test(values, begin, length)) { - return super.evaluate(values, begin, length) / ((double) length); + return sum.evaluate(values) / ((double) length); } return Double.NaN; } - } \ No newline at end of file diff --git a/src/java/org/apache/commons/math/stat/univariate/moment/Variance.java b/src/java/org/apache/commons/math/stat/univariate/moment/Variance.java index 731e6cbf9..202b0843b 100644 --- a/src/java/org/apache/commons/math/stat/univariate/moment/Variance.java +++ b/src/java/org/apache/commons/math/stat/univariate/moment/Variance.java @@ -53,17 +53,11 @@ */ package org.apache.commons.math.stat.univariate.moment; -import org - .apache - .commons - .math - .stat - .univariate - .AbstractStorelessUnivariateStatistic; +import org.apache.commons.math.stat.univariate.AbstractStorelessUnivariateStatistic; /** * - * @version $Revision: 1.6 $ $Date: 2003/07/09 20:04:10 $ + * @version $Revision: 1.7 $ $Date: 2003/07/15 03:36:36 $ */ public class Variance extends AbstractStorelessUnivariateStatistic { @@ -84,7 +78,8 @@ public class Variance extends AbstractStorelessUnivariateStatistic { this.moment = m2; } /** - * @see org.apache.commons.math.stat.univariate.StorelessUnivariateStatistic#increment(double) + * @see org.apache.commons.math.stat.univariate. + * StorelessUnivariateStatistic#increment(double) */ public void increment(double d) { if (incMoment) { @@ -93,7 +88,8 @@ public class Variance extends AbstractStorelessUnivariateStatistic { } /** - * @see org.apache.commons.math.stat.univariate.StorelessUnivariateStatistic#getValue() + * @see org.apache.commons.math.stat.univariate. + * StorelessUnivariateStatistic#getValue() */ public double getResult() { if (n < moment.n) { @@ -111,7 +107,8 @@ public class Variance extends AbstractStorelessUnivariateStatistic { } /** - * @see org.apache.commons.math.stat.univariate.StorelessUnivariateStatistic#clear() + * @see org.apache.commons.math.stat.univariate. + * StorelessUnivariateStatistic#clear() */ public void clear() { if (incMoment) { @@ -122,7 +119,6 @@ public class Variance extends AbstractStorelessUnivariateStatistic { } /*UnvariateStatistic Approach */ - Mean mean = new Mean(); /** @@ -140,7 +136,8 @@ public class Variance extends AbstractStorelessUnivariateStatistic { * @param length processing at this point in the array * @return the result, Double.NaN if no values for an empty array * or 0.0 for a single value set. - * @see org.apache.commons.math.stat.univariate.UnivariateStatistic#evaluate(double[], int, int) + * @see org.apache.commons.math.stat.univariate. + * UnivariateStatistic#evaluate(double[], int, int) */ public double evaluate(double[] values, int begin, int length) { diff --git a/src/java/org/apache/commons/math/stat/univariate/package.html b/src/java/org/apache/commons/math/stat/univariate/package.html new file mode 100644 index 000000000..6f61da526 --- /dev/null +++ b/src/java/org/apache/commons/math/stat/univariate/package.html @@ -0,0 +1,35 @@ + + +

UnivariateStatistic API Usage Examples:

+ +

UnivariateStatistic:

+ + +/* evaluation approach */
+double[] values = new double[] { 1, 2, 3, 4, 5 };
+UnivariateStatistic stat = new Mean();
+System.out.println("mean = " + +stat.evaluate(values));
+ + +

StorelessUnivariateStatistic:

+ + +/* incremental approach */
+double[] values = new double[] { 1, 2, 3, 4, 5 };
+StorelessUnivariateStatistic stat = +new Mean();
+System.out.println("mean before adding a value is NaN = " + stat.getResult());
+for (int i = 0; i < values.length; i++) {
+    stat.increment(values[i]);
+    System.out.println("current mean = " + stat2.getResult());
+}
+ stat.clear();
+System.out.println("mean after clear is NaN = " + stat.getResult()); + + + + diff --git a/src/java/org/apache/commons/math/stat/univariate/summary/Sum.java b/src/java/org/apache/commons/math/stat/univariate/summary/Sum.java index 706264ad7..ee617f78d 100644 --- a/src/java/org/apache/commons/math/stat/univariate/summary/Sum.java +++ b/src/java/org/apache/commons/math/stat/univariate/summary/Sum.java @@ -53,6 +53,7 @@ */ package org.apache.commons.math.stat.univariate.summary; +import org.apache.commons.collections.primitives.DoubleIterator; import org .apache .commons @@ -62,7 +63,7 @@ import org .AbstractStorelessUnivariateStatistic; /** - * @version $Revision: 1.6 $ $Date: 2003/07/09 20:04:13 $ + * @version $Revision: 1.7 $ $Date: 2003/07/15 03:37:11 $ */ public class Sum extends AbstractStorelessUnivariateStatistic { @@ -75,10 +76,10 @@ public class Sum extends AbstractStorelessUnivariateStatistic { * @see org.apache.commons.math.stat.univariate.StorelessUnivariateStatistic#increment(double) */ public void increment(double d) { - if (Double.isNaN(value )) { - value = d; + if (Double.isNaN(value)) { + value = d; } else { - value += d; + value += d; } } @@ -88,7 +89,7 @@ public class Sum extends AbstractStorelessUnivariateStatistic { public double getResult() { return value; } - + /** * @see org.apache.commons.math.stat.univariate.StorelessUnivariateStatistic#clear() */ @@ -115,6 +116,4 @@ public class Sum extends AbstractStorelessUnivariateStatistic { return sum; } - - }