minor javadoc cleanup

git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/math/trunk@140985 13f79535-47bb-0310-9956-ffa450edef68

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();
     }
+
 }

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;
 

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();
 
 }

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); 
 
 }

src/java/org/apache/commons/math/stat/univariate/moment/FirstMoment.java

@@ -62,7 +62,7 @@ import org.apache.commons.math.stat.univariate.AbstractStorelessUnivariateStatis
  * <a href="http://www.spss.com/tech/stat/Algorithms/11.5/descriptives.pdf">
  * recursive strategy
  * </a>. 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;

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 <a href="http://www.xycoon.com/arithmetic_mean.htm">
  * arithmetic mean </a> 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 <a href="http://www.xycoon.com/arithmetic_mean.htm">
@@ -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;
     }
-
 }

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) {
 

src/java/org/apache/commons/math/stat/univariate/package.html

@@ -0,0 +1,35 @@
+<html>
+<body>
+<h3>UnivariateStatistic API Usage Examples:</h3>
+
+<h4>UnivariateStatistic:</h4>
+
+<code> 
+/* evaluation approach */<br/>
+double[] values = new double[] { 1, 2, 3, 4, 5 };<br/>
+<span style="font-weight: bold;">UnivariateStatistic stat = new Mean();</span><br/>
+System.out.println("mean = " + 
+<span style="font-weight: bold;">stat.evaluate(values)</span>);<br/>
+</code>
+
+<h4>StorelessUnivariateStatistic:</h4>
+
+<code> 
+/* incremental approach */<br>
+double[] values = new double[] { 1, 2, 3, 4, 5 };<br/>
+<span style="font-weight: bold;">StorelessUnivariateStatistic stat =
+new Mean();</span><br/>
+System.out.println("mean before adding a value is NaN = " + <span
+ style="font-weight: bold;">stat.getResult()</span>);<br/>
+for (int i = 0; i &lt; values.length; i++) {<br/>
+&nbsp;&nbsp;&nbsp; <span style="font-weight: bold;">stat.increment(values[i]);</span><br>
+&nbsp;&nbsp;&nbsp; System.out.println("current mean = " + <span
+ style="font-weight: bold;">stat2.getResult()</span>);<br/>
+}<br>
+<span style="font-weight: bold;"> stat.clear();</span><br/>
+System.out.println("mean after clear is NaN = " + <span
+ style="font-weight: bold;">stat.getResult()</span>); 
+</code>
+
+</body>
+</html>

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;
     }
 
-
-
 }