In cases where "getResult" contains a statistical calculation, it now

checks if the internal state of the underlying statistic has changed 
and only recalculates if this is true. this way muliple calls to getResult 
when the staistic has not been incremented are less expensive 
because it is only returning a property value.


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

src/java/org/apache/commons/math/stat/univariate/AbstractStorelessUnivariateStatistic.java

@@ -57,9 +57,8 @@ package org.apache.commons.math.stat.univariate;
  *
  * Abstract Implementation for StorelessUnivariateStatistics.
  * Provides the ability to extend polymophically so that
- * indiviual statistics do not need to implement these methods
+ * indiviual statistics do not need to implement these methods unless
- * 
+ * there are better algorithms for handling the calculation.
- * @author Mark Diggory
  */
 public abstract class AbstractStorelessUnivariateStatistic
     extends AbstractUnivariateStatistic
@@ -67,7 +66,9 @@ public abstract class AbstractStorelessUnivariateStatistic
 
     /**
      * This implements the AbstractUnivariateStatistic impl to funnel 
-     * calculation off to the instantanious increment method.
+     * 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)
      */
     public double evaluate(double[] values, int begin, int length) {
@@ -77,6 +78,6 @@ public abstract class AbstractStorelessUnivariateStatistic
                 increment(values[i]);
             }
         }
-        return getValue();
+        return getResult();
     }
 }

src/java/org/apache/commons/math/stat/univariate/AbstractUnivariateStatistic.java

@@ -57,8 +57,6 @@ 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. 
- * 
- * @author Mark Diggory
  */
 public abstract class AbstractUnivariateStatistic
     implements UnivariateStatistic {

src/java/org/apache/commons/math/stat/univariate/StorelessUnivariateStatistic.java

@@ -55,9 +55,11 @@ package org.apache.commons.math.stat.univariate;
 
 /**
  * StorelessUnivariate interface provides methods to increment and access
- * the internal state of the Statistic.
+ * the internal state of the Statistic. A StorelessUnivariateStatistic does
- *
+ * not require that a double[] storage structure be maintained with the values
- * @author Mark Diggory
+ * 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.
  */
 public interface StorelessUnivariateStatistic extends UnivariateStatistic {
 
@@ -65,19 +67,16 @@ public interface StorelessUnivariateStatistic extends UnivariateStatistic {
      * Increments the internal state of the Storagless
      * Implementation.
      * @param d is the value to increment the state by.
-     * @return the new state of this Statistic. Returns 
-     * the same value as <code>getValue()</code>, Double.NaN if it
-     * has been cleared or just instantiated.
      */
     public void increment(double d);
 
     /**
      * Returns the current state of the statistic after the
      * last increment.
-     * @return values of the statistic, Double.NaN if it
+     * @return value of the statistic, Double.NaN if it
      * has been cleared or just instantiated.
      */
-    public double getValue();
+    public double getResult();
 
 
     /**
@@ -85,22 +84,4 @@ public interface StorelessUnivariateStatistic extends UnivariateStatistic {
      */
     public void clear();
 
-    /**
-     * Returns the behavior of this statistic when evaluating
-     * double[]'s using <code>evaluate(double[], int, int)</code> and
-     * <code>evaluate(double[])</code> methods.
-     * @return the state
-     */
-    //public boolean isClearOnEval();
-
-    /**
-     * Sets the behavior of this statistic when evaluating
-     * double[]'s using <code>evaluate(double[], int, int)</code> and
-     * <code>evaluate(double[])</code> methods. if true, the internal state
-     * will be cleared between evaluations, otherwise it will be
-     * incrimented.
-     * @param b true | false
-     */
-    //public void setClearOnEval(boolean b);
-
 }

src/java/org/apache/commons/math/stat/univariate/UnivariateStatistic.java

@@ -54,8 +54,6 @@
 package org.apache.commons.math.stat.univariate;
 
 /**
- * @author Mark Diggory
- *
  * UnivariateStatistic interface provides methods to evaluate 
  * double[] based content using a particular algorithm.
  * 

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

@@ -88,7 +88,7 @@ public class FirstMoment extends AbstractStorelessUnivariateStatistic {
         n0 = (double)n;
         v = dev / n0;
 
-        m1 += v;                    
+        m1 += v;                   
     }
     
     /**
@@ -99,13 +99,13 @@ public class FirstMoment extends AbstractStorelessUnivariateStatistic {
         n = 0;
         dev = 0.0;
         v = 0.0;
-        n0 = 0.0;
+        n0 = 0.0;  
     }
     
     /**
      * @see org.apache.commons.math.stat.univariate.StorelessUnivariateStatistic#getValue()
      */
-    public double getValue() {
+    public double getResult() {
         return m1;
     }
 

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

@@ -95,7 +95,7 @@ public class FourthMoment extends ThirdMoment {
     /**
      * @see org.apache.commons.math.stat.univariate.StorelessUnivariateStatistic#getValue()
      */
-    public double getValue() {
+    public double getResult() {
         return m4;
     }
 

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

@@ -60,9 +60,12 @@ import org.apache.commons.math.stat.univariate.summary.SumOfLogs;
  *
  */
 public class GeometricMean extends SumOfLogs {
- 
+
-    private int n = 0;
+    protected int n = 0;
+
+    private double geoMean = Double.NaN;
     
+    private double lastSum = 0.0;
     /**
      * @see org.apache.commons.math.stat.univariate.StorelessUnivariateStatistic#increment(double)
      */
@@ -74,8 +77,12 @@ public class GeometricMean extends SumOfLogs {
     /**
      * @see org.apache.commons.math.stat.univariate.StorelessUnivariateStatistic#getValue()
      */
-    public double getValue() {
+    public double getResult() {
-        return Math.exp( super.getValue() / (double)n );
+        if (lastSum != super.getResult() || n == 1) {
+            lastSum = super.getResult();
+            geoMean = Math.exp(lastSum / (double) n);
+        }
+        return geoMean;
     }
 
     /**
@@ -83,9 +90,11 @@ public class GeometricMean extends SumOfLogs {
      */
     public void clear() {
         super.clear();
+        lastSum = 0.0;
+        geoMean = Double.NaN;
         n = 0;
     }
-    
+
     /**
      * Returns the geometric mean for this collection of values
      * @param values Is a double[] containing the values
@@ -96,9 +105,8 @@ public class GeometricMean extends SumOfLogs {
      * @see org.apache.commons.math.stat.univariate.UnivariateStatistic#evaluate(double[], int, int)
      */
     public double evaluate(double[] values, int begin, int length) {
-        return Math.exp(super.evaluate(values, begin, length) / (double) length );
+        return Math.exp(
+            super.evaluate(values, begin, length) / (double) length);
     }
 
-
-
 }

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

@@ -70,6 +70,10 @@ public class Kurtosis extends AbstractStorelessUnivariateStatistic {
 
     protected boolean incMoment = true;
 
+    private double kurtosis = Double.NaN;
+
+    private int n = 0;
+    
     public Kurtosis() {
         moment = new FourthMoment();
     }
@@ -91,23 +95,31 @@ public class Kurtosis extends AbstractStorelessUnivariateStatistic {
     /**
      * @see org.apache.commons.math.stat.univariate.StorelessUnivariateStatistic#getValue()
      */
-    public double getValue() {
+    public double getResult() {
+        if (n < moment.n) {
+            if (moment.n <= 0) {
+                kurtosis = Double.NaN;
+            }
 
-        if (moment.n <= 0) {
+            double variance =
-            return Double.NaN;
+                (moment.n < 1) ? 0.0 : moment.m2 / (double) (moment.n - 1);
+
+            if (moment.n <= 3 || variance < 10E-20) {
+                kurtosis = 0.0;
+            } else {
+                kurtosis =
+                    (moment.n0 * (moment.n0 + 1) * moment.m4
+                        - 3 * moment.m2 * moment.m2 * moment.n1)
+                        / (moment.n1
+                            * moment.n2
+                            * moment.n3
+                            * variance
+                            * variance);
+            }
+            n = moment.n;
         }
-
+        
-        double variance =
+        return kurtosis;
-            (moment.n < 1) ? 0.0 : moment.m2 / (double) (moment.n - 1);
-
-        if (moment.n <= 3 || variance < 10E-20) {
-            return 0.0;
-        }
-
-        return (moment.n0 * (moment.n0 + 1) * moment.m4
-                - 3 * moment.m2 * moment.m2 * moment.n1)
-                / (moment.n1 * moment.n2 * moment.n3 * variance * variance);
-
     }
 
     /**
@@ -117,6 +129,8 @@ public class Kurtosis extends AbstractStorelessUnivariateStatistic {
         if (incMoment) {
             moment.clear();
         }
+        kurtosis = Double.NaN;
+        n = 0;
     }
 
     /*UnvariateStatistic Approach */
@@ -125,12 +139,13 @@ public class Kurtosis extends AbstractStorelessUnivariateStatistic {
 
     /**
     * This algorithm uses a corrected two pass algorithm of the following 
-    * <a href="http://lib-www.lanl.gov/numerical/bookcpdf/c14-1.pdf">
+     * <a href="http://lib-www.lanl.gov/numerical/bookcpdf/c14-1.pdf">
-    * corrected two pass formula (14.1.8)</a>, and also referenced in:<p/>
+     * corrected two pass formula (14.1.8)</a>, and also referenced in:
-    * "Algorithms for Computing the Sample Variance: Analysis and
+     * <p>
-    * Recommendations", Chan, T.F., Golub, G.H., and LeVeque, R.J. 
+     * "Algorithms for Computing the Sample Variance: Analysis and
-    * 1983, American Statistician, vol. 37, pp. 242?247.
+     * Recommendations", Chan, T.F., Golub, G.H., and LeVeque, R.J. 
-    * <p/>
+     * 1983, American Statistician, vol. 37, pp. 242?247.
+     * </p>
     * Returns the kurtosis for this collection of values. Kurtosis is a 
     * measure of the "peakedness" of a distribution.
     * @param values Is a double[] containing the values

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

@@ -102,16 +102,16 @@ public class Mean extends AbstractStorelessUnivariateStatistic {
     /**
      * @see org.apache.commons.math.stat.univariate.StorelessUnivariateStatistic#getValue()
      */
-    public double getValue() {
+    public double getResult() {
         return moment.m1;
     }
-
+    
     /*UnvariateStatistic Approach */
     Sum sum = new Sum();
 
     /**
      * Returns the <a href=http://www.xycoon.com/arithmetic_mean.htm>
-     * arithmetic mean </a> of the available values 
+     * arithmetic mean </a> of the available values.
      * @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

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

@@ -80,6 +80,7 @@ public class SecondMoment extends FirstMoment {
         
         /* increment and return m2 */
         m2 += n1 * dev * v;
+
     }
 
     /**
@@ -94,7 +95,7 @@ public class SecondMoment extends FirstMoment {
     /**
      * @see org.apache.commons.math.stat.univariate.StorelessUnivariateStatistic#getValue()
      */
-    public double getValue() {
+    public double getResult() {
         return m2;
     }
 

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

@@ -71,6 +71,10 @@ public class Skewness extends AbstractStorelessUnivariateStatistic {
 
     protected boolean incMoment = true;
 
+    protected double skewness = Double.NaN;
+
+    private int n = 0;
+    
     public Skewness() {
         moment = new ThirdMoment();
     }
@@ -92,20 +96,28 @@ public class Skewness extends AbstractStorelessUnivariateStatistic {
     /**
      * @see org.apache.commons.math.stat.univariate.StorelessUnivariateStatistic#getValue()
      */
-    public double getValue() {
+    public double getResult() {
-        if (moment.n <= 0) {
+        if (n < moment.n) {
-            return Double.NaN;
+            if (moment.n <= 0) {
+                skewness = Double.NaN;
+            }
+
+            double variance =
+                (moment.n < 1) ? 0.0 : moment.m2 / (double) (moment.n - 1);
+
+            if (moment.n <= 2 || variance < 10E-20) {
+                skewness = 0.0;
+            } else {
+                skewness =
+                    (moment.n0 * moment.m3)
+                        / (moment.n1
+                            * moment.n2
+                            * Math.sqrt(variance)
+                            * variance);
+            }
+            n = moment.n;
         }
-
+        return skewness;
-        double variance =
-            (moment.n < 1) ? 0.0 : moment.m2 / (double) (moment.n - 1);
-
-        if (moment.n <= 2 || variance < 10E-20) {
-            return 0.0;
-        }
-
-        return (moment.n0 * moment.m3)
-                / (moment.n1 * moment.n2 * Math.sqrt(variance) * variance);
     }
 
     /**
@@ -115,8 +127,10 @@ public class Skewness extends AbstractStorelessUnivariateStatistic {
         if (incMoment) {
             moment.clear();
         }
+        skewness = Double.NaN;
+        n = 0;
     }
-
+    
     /*UnvariateStatistic Approach */
 
     Mean mean = new Mean();
@@ -124,11 +138,12 @@ public class Skewness extends AbstractStorelessUnivariateStatistic {
     /**
      * This algorithm uses a corrected two pass algorithm of the following 
      * <a href="http://lib-www.lanl.gov/numerical/bookcpdf/c14-1.pdf">
-     * corrected two pass formula (14.1.8)</a>, and also referenced in:<p/>
+     * corrected two pass formula (14.1.8)</a>, and also referenced in:
+     * <p>
      * "Algorithms for Computing the Sample Variance: Analysis and
      * Recommendations", Chan, T.F., Golub, G.H., and LeVeque, R.J. 
      * 1983, American Statistician, vol. 37, pp. 242?247.
-     * <p/>
+     * </p>
      * Returns the skewness of a collection of values.  Skewness is a 
      * measure of the assymetry of a given distribution. 
      * @param values Is a double[] containing the values

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

@@ -59,42 +59,48 @@ package org.apache.commons.math.stat.univariate.moment;
  */
 public class StandardDeviation extends Variance {
 
-    public StandardDeviation(){
+    protected double std = Double.NaN;
+
+    private double lastVar = 0.0;
+    
+    public StandardDeviation() {
         super();
     }
-    
+
-    public StandardDeviation(SecondMoment m2){
+    public StandardDeviation(SecondMoment m2) {
         super(m2);
     }
-    
+
     /**
      * @see org.apache.commons.math.stat.univariate.StorelessUnivariateStatistic#increment(double)
      */
     public void increment(double d) {
-        super.increment(d);        
+        super.increment(d);
     }
-    
+
     /**
      * @see org.apache.commons.math.stat.univariate.StorelessUnivariateStatistic#getValue()
      */
-    public double getValue() {
+    public double getResult() {
-        
+        if (lastVar != super.getResult()) {
-        double var = super.getValue();
+            lastVar = super.getResult();
-        
+            if (Double.isNaN(lastVar)) {
-        if(Double.isNaN(var)){
+                std = Double.NaN;
-            return Double.NaN;
+            } else if (lastVar == 0.0) {
-        }else if (var == 0.0){
+                std = 0.0;
-            return 0.0;
+            } else {
+                std = Math.sqrt(lastVar);
+            }
         }
-        
+        return std;
-        return Math.sqrt(var);
     }
-    
+
     /**
      * @see org.apache.commons.math.stat.univariate.StorelessUnivariateStatistic#clear()
      */
     public void clear() {
         super.clear();
+        lastVar = 0.0;
     }
 
     /**
@@ -108,8 +114,8 @@ public class StandardDeviation extends Variance {
      */
     public double evaluate(double[] values, int begin, int length) {
         double var = super.evaluate(values, begin, length);
-        
+
-        if(Double.isNaN(var)){
+        if (Double.isNaN(var)) {
             return Double.NaN;
         }
 

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

@@ -95,7 +95,7 @@ public class ThirdMoment extends SecondMoment{
     /**
      * @see org.apache.commons.math.stat.univariate.StorelessUnivariateStatistic#getValue()
      */
-    public double getValue() {
+    public double getResult() {
         return m3;
     }
 

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

@@ -71,6 +71,10 @@ public class Variance extends AbstractStorelessUnivariateStatistic {
 
     protected boolean incMoment = true;
 
+    protected double variance = Double.NaN;
+
+    protected int n = 0;
+    
     public Variance() {
         moment = new SecondMoment();
     }
@@ -91,13 +95,19 @@ public class Variance extends AbstractStorelessUnivariateStatistic {
     /**
      * @see org.apache.commons.math.stat.univariate.StorelessUnivariateStatistic#getValue()
      */
-    public double getValue() {
+    public double getResult() {
-        if (moment.n <= 0) {
+        if (n < moment.n) {
-            return Double.NaN;
+            if (moment.n <= 0) {
-        } else if (moment.n <= 1) {
+                variance = Double.NaN;
-            return 0.0;
+            } else if (moment.n <= 1) {
+                variance = 0.0;
+            } else {
+                variance = moment.m2 / (moment.n0 - 1); 
+            }
+            n = moment.n;
         }
-        return moment.m2 / (moment.n0 - 1);
+
+        return variance;
     }
 
     /**
@@ -107,6 +117,8 @@ public class Variance extends AbstractStorelessUnivariateStatistic {
         if (incMoment) {
             moment.clear();
         }
+        variance = Double.NaN;
+        n = 0;
     }
 
     /*UnvariateStatistic Approach */
@@ -117,11 +129,12 @@ public class Variance extends AbstractStorelessUnivariateStatistic {
      * Returns the variance of the available values. This uses a corrected
      * two pass algorithm of the following 
      * <a href="http://lib-www.lanl.gov/numerical/bookcpdf/c14-1.pdf">
-     * corrected two pass formula (14.1.8)</a>, and also referenced in:<p/>
+     * corrected two pass formula (14.1.8)</a>, and also referenced in:
+     * <p>
      * "Algorithms for Computing the Sample Variance: Analysis and
      * Recommendations", Chan, T.F., Golub, G.H., and LeVeque, R.J. 
      * 1983, American Statistician, vol. 37, pp. 242?247.
-     * 
+     * </p>
      * @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

src/java/org/apache/commons/math/stat/univariate/rank/Max.java

@@ -85,7 +85,7 @@ public class Max extends AbstractStorelessUnivariateStatistic {
     /**
      * @see org.apache.commons.math.stat.univariate.StorelessUnivariateStatistic#getValue()
      */
-    public double getValue() {
+    public double getResult() {
         return value;
     }
 

src/java/org/apache/commons/math/stat/univariate/rank/Min.java

@@ -85,7 +85,7 @@ public class Min extends AbstractStorelessUnivariateStatistic {
     /**
      * @see org.apache.commons.math.stat.univariate.StorelessUnivariateStatistic#getValue()
      */
-    public double getValue() {
+    public double getResult() {
         return value;
     }
 

src/java/org/apache/commons/math/stat/univariate/summary/Product.java

@@ -85,7 +85,7 @@ public class Product extends AbstractStorelessUnivariateStatistic {
     /**
      * @see org.apache.commons.math.stat.univariate.StorelessUnivariateStatistic#getValue()
      */
-    public double getValue() {
+    public double getResult() {
         return value;
     }
 

src/java/org/apache/commons/math/stat/univariate/summary/Sum.java

@@ -85,7 +85,7 @@ public class Sum extends AbstractStorelessUnivariateStatistic {
     /**
      * @see org.apache.commons.math.stat.univariate.StorelessUnivariateStatistic#getValue()
      */
-    public double getValue() {
+    public double getResult() {
         return value;
     }
     

src/java/org/apache/commons/math/stat/univariate/summary/SumOfLogs.java

@@ -87,7 +87,7 @@ public class SumOfLogs extends AbstractStorelessUnivariateStatistic {
     /**
      * @see org.apache.commons.math.stat.univariate.StorelessUnivariateStatistic#getValue()
      */
-    public double getValue() {
+    public double getResult() {
         return value;
     }
 

src/java/org/apache/commons/math/stat/univariate/summary/SumOfSquares.java

@@ -85,7 +85,7 @@ public class SumOfSquares extends AbstractStorelessUnivariateStatistic {
     /**
      * @see org.apache.commons.math.stat.univariate.StorelessUnivariateStatistic#getValue()
      */
-    public double getValue() {
+    public double getResult() {
         return value;
     }