Added support for population standard deviation.

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

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

@@ -21,16 +21,20 @@ import org.apache.commons.math.stat.descriptive.AbstractStorelessUnivariateStati
 
 /**
  * Computes the sample standard deviation.  The standard deviation
- * is the positive square root of the variance.  See {@link Variance} for
+ * is the positive square root of the variance.  This implementation wraps a
- * more information.  This implementation wraps a {@link Variance}
+ * {@link Variance} instance.  The <code>isBiasCorrected</code> property of the
- * instance.
+ * wrapped Variance instance is exposed, so that this class can be used to
+ * compute both the "sample standard deviation" (the square root of the 
+ * bias-corrected "sample variance") or the "population standard deviation"
+ * (the square root of the non-bias-corrected "population variance"). See 
+ * {@link Variance} for more information.  
  * <p>
  * <strong>Note that this implementation is not synchronized.</strong> If 
  * multiple threads access an instance of this class concurrently, and at least
  * one of the threads invokes the <code>increment()</code> or 
  * <code>clear()</code> method, it must be synchronized externally.
  * 
- * @version $Revision: 1.1 $ $Date: 2004/10/08 05:08:17 $
+ * @version $Revision: 1.2 $ $Date: 2004/10/11 06:54:05 $
  */
 public class StandardDeviation extends AbstractStorelessUnivariateStatistic
     implements Serializable {
@@ -42,7 +46,8 @@ public class StandardDeviation extends AbstractStorelessUnivariateStatistic
     private Variance variance = null;
 
     /**
-     * Constructs a StandardDeviation
+     * Constructs a StandardDeviation.  Sets the underlying {@link Variance}
+     * instance's <code>isBiasCorrected</code> property to true.
      */
     public StandardDeviation() {
         variance = new Variance();
@@ -56,6 +61,35 @@ public class StandardDeviation extends AbstractStorelessUnivariateStatistic
     public StandardDeviation(final SecondMoment m2) {
         variance = new Variance(m2);
     }
+    
+    /**
+     * Contructs a StandardDeviation with the specified value for the
+     * <code>isBiasCorrected</code> property.  If this property is set to 
+     * <code>true</code>, the {@link Variance} used in computing results will
+     * use the bias-corrected, or "sample" formula.  See {@link Variance} for
+     * details.
+     * 
+     * @param isBiasCorrected  whether or not the variance computation will use
+     * the bias-corrected formula
+     */
+    public StandardDeviation(boolean isBiasCorrected) {
+        variance = new Variance(isBiasCorrected);
+    }
+    
+    /**
+     * Contructs a StandardDeviation with the specified value for the
+     * <code>isBiasCorrected</code> property and the supplied external moment.
+     * If <code>isBiasCorrected</code> is set to <code>true</code>, the
+     * {@link Variance} used in computing results will use the bias-corrected,
+     * or "sample" formula.  See {@link Variance} for details.
+     * 
+     * @param isBiasCorrected  whether or not the variance computation will use
+     * the bias-corrected formula
+      * @param m2 the external moment
+     */
+    public StandardDeviation(boolean isBiasCorrected, SecondMoment m2) {
+        variance = new Variance(isBiasCorrected, m2);
+    }
 
     /**
      * @see org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#increment(double)
@@ -103,7 +137,6 @@ public class StandardDeviation extends AbstractStorelessUnivariateStatistic
         return Math.sqrt(variance.evaluate(values));
     }
     
-    
     /**
      * Returns the Standard Deviation of the entries in the specified portion of
      * the input array, or <code>Double.NaN</code> if the designated subarray
@@ -179,4 +212,18 @@ public class StandardDeviation extends AbstractStorelessUnivariateStatistic
     public double evaluate(final double[] values, final double mean)  {
         return Math.sqrt(variance.evaluate(values, mean));
     }
+    
+    /**
+     * @return Returns the isBiasCorrected.
+     */
+    public boolean isBiasCorrected() {
+        return variance.isBiasCorrected();
+    }
+
+    /**
+     * @param isBiasCorrected The isBiasCorrected to set.
+     */
+    public void setBiasCorrected(boolean isBiasCorrected) {
+        variance.setBiasCorrected(isBiasCorrected);
+    }
 }

src/test/org/apache/commons/math/stat/descriptive/moment/StandardDeviationTest.java

@@ -24,7 +24,7 @@ import org.apache.commons.math.stat.descriptive.UnivariateStatistic;
 /**
  * Test cases for the {@link UnivariateStatistic} class.
  * 
- * @version $Revision: 1.1 $ $Date: 2004/10/08 05:08:20 $
+ * @version $Revision: 1.2 $ $Date: 2004/10/11 06:54:05 $
  */
 public class StandardDeviationTest extends StorelessUnivariateStatisticAbstractTest{
 
@@ -67,5 +67,38 @@ public class StandardDeviationTest extends StorelessUnivariateStatisticAbstractT
         std.increment(1d);
         assertEquals(0d, std.getResult(), 0);
     }
+    
+    /**
+     * Test population version of variance
+     */ 
+    public void testPopulation() {
+        double[] values = {-1.0d, 3.1d, 4.0d, -2.1d, 22d, 11.7d, 3d, 14d};
+        double sigma = populationStandardDeviation(values);
+        SecondMoment m = new SecondMoment();
+        m.evaluate(values);  // side effect is to add values
+        StandardDeviation s1 = new StandardDeviation();
+        s1.setBiasCorrected(false);
+        assertEquals(sigma, s1.evaluate(values), 1E-14);
+        s1.incrementAll(values);
+        assertEquals(sigma, s1.getResult(), 1E-14);
+        s1 = new StandardDeviation(false, m);
+        assertEquals(sigma, s1.getResult(), 1E-14);     
+        s1 = new StandardDeviation(false);
+        assertEquals(sigma, s1.evaluate(values), 1E-14);
+        s1.incrementAll(values);
+        assertEquals(sigma, s1.getResult(), 1E-14);     
+    }
+    
+    /**
+     * Definitional formula for population standard deviation
+     */
+    protected double populationStandardDeviation(double[] v) {
+        double mean = new Mean().evaluate(v);
+        double sum = 0;
+        for (int i = 0; i < v.length; i++) {
+            sum += (v[i] - mean) * (v[i] - mean); 
+        }
+        return Math.sqrt(sum / (double) v.length);
+    }
 
 }