Author: psteitz
Date: Sun Jun 10 21:42:56 2007
New Revision: 546001
URL: http://svn.apache.org/viewvc?view=rev&rev=546001
Log:
Javadoc only. Made it clear that increment-getResult uses a different,
less accurate, computing formula than evaluate for Variance.
JIRA: MATH-163
Modified:
jakarta/commons/proper/math/trunk/src/java/org/apache/commons/math/stat/descriptive/AbstractStorelessUnivariateStatistic.java
jakarta/commons/proper/math/trunk/src/java/org/apache/commons/math/stat/descriptive/moment/Variance.java
Modified:
jakarta/commons/proper/math/trunk/src/java/org/apache/commons/math/stat/descriptive/AbstractStorelessUnivariateStatistic.java
URL:
http://svn.apache.org/viewvc/jakarta/commons/proper/math/trunk/src/java/org/apache/commons/math/stat/descriptive/AbstractStorelessUnivariateStatistic.java?view=diff&rev=546001&r1=546000&r2=546001
==============================================================================
---
jakarta/commons/proper/math/trunk/src/java/org/apache/commons/math/stat/descriptive/AbstractStorelessUnivariateStatistic.java
(original)
+++
jakarta/commons/proper/math/trunk/src/java/org/apache/commons/math/stat/descriptive/AbstractStorelessUnivariateStatistic.java
Sun Jun 10 21:42:56 2007
@@ -46,8 +46,9 @@
* statistic. Its side effects are the same as invoking [EMAIL PROTECTED]
#clear} and
* then [EMAIL PROTECTED] #incrementAll(double[])}.
* <p>
- * Implementations may override this method with a more efficient
- * implementation that works directly with the input array.
+ * Implementations may override this method with a more efficient and
+ * possibly more accurate implementation that works directly with the
+ * input array.
* <p>
* If the array is null, an IllegalArgumentException is thrown.
*
@@ -69,8 +70,9 @@
* statistic. Its side effects are the same as invoking [EMAIL PROTECTED]
#clear} and
* then [EMAIL PROTECTED] #incrementAll(double[], int, int)}.
* <p>
- * Implementations may override this method with a more efficient
- * implementation that works directly with the input array.
+ * Implementations may override this method with a more efficient and
+ * possibly more accurate implementation that works directly with the
+ * input array.
* <p>
* If the array is null or the index parameters are not valid, an
* IllegalArgumentException is thrown.
Modified:
jakarta/commons/proper/math/trunk/src/java/org/apache/commons/math/stat/descriptive/moment/Variance.java
URL:
http://svn.apache.org/viewvc/jakarta/commons/proper/math/trunk/src/java/org/apache/commons/math/stat/descriptive/moment/Variance.java?view=diff&rev=546001&r1=546000&r2=546001
==============================================================================
---
jakarta/commons/proper/math/trunk/src/java/org/apache/commons/math/stat/descriptive/moment/Variance.java
(original)
+++
jakarta/commons/proper/math/trunk/src/java/org/apache/commons/math/stat/descriptive/moment/Variance.java
Sun Jun 10 21:42:56 2007
@@ -21,7 +21,7 @@
import
org.apache.commons.math.stat.descriptive.AbstractStorelessUnivariateStatistic;
/**
- * Computes the variance of the available values. By default, the unbiased
+ * Computes the variance of the available values. By default, the unbiased
* "sample variance" definitional formula is used:
* <p>
* variance = sum((x_i - mean)^2) / (n - 1)
@@ -30,21 +30,34 @@
* of sample observations.
* <p>
* The definitional formula does not have good numerical properties, so
- * this implementation uses updating formulas based on West's algorithm
- * as described in <a href="http://doi.acm.org/10.1145/359146.359152";>
- * Chan, T. F. and J. G. Lewis 1979, <i>Communications of the ACM</i>,
- * vol. 22 no. 9, pp. 526-531.</a>.
+ * this implementation does not compute the statistic using the definitional
+ * formula. <ul>
+ * <li> The <code>getResult</code> method computes the variance using
+ * updating formulas based on West's algorithm, as described in
+ * <a href="http://doi.acm.org/10.1145/359146.359152";> Chan, T. F. and
+ * J. G. Lewis 1979, <i>Communications of the ACM</i>,
+ * vol. 22 no. 9, pp. 526-531.</a></li>
+ * <li> The <code>evaluate</code> methods leverage the fact that they have the
+ * full array of values in memory to execute a two-pass algorithm.
+ * Specifically, these methods use the "corrected two-pass algorithm" from
+ * Chan, Golub, Levesque, <i>Algorithms for Computing the Sample Variance</i>,
+ * American Statistician, August 1983.</li></ul>
+ * Note that adding values using <code>increment</code> or
+ * <code>incrementAll</code> and then executing <code>getResult</code> will
+ * sometimes give a different, less accurate, result than executing
+ * <code>evaluate</code> with the full array of values. The former approach
+ * should only be used when the full array of values is not available.
* <p>
* The "population variance" ( sum((x_i - mean)^2) / n ) can also
* be computed using this statistic. The <code>isBiasCorrected</code>
* property determines whether the "population" or "sample" value is
* returned by the <code>evaluate</code> and <code>getResult</code> methods.
* To compute population variances, set this property to <code>false.</code>
- *
+ * <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.
+ * <code>clear()</code> method, it must be synchronized externally.</p>
*
* @version $Revision$ $Date$
*/
@@ -118,7 +131,13 @@
}
/**
- * @see
org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#increment(double)
+ * [EMAIL PROTECTED]
+ * <p>If all values are available, it is more accurate to use
+ * [EMAIL PROTECTED] #evaluate(double[])} rather than adding values one at
a time
+ * using this method and then executing [EMAIL PROTECTED] #getResult},
since
+ * <code>evaluate</code> leverages the fact that is has the full
+ * list of values together to execute a two-pass algorithm.
+ * See [EMAIL PROTECTED] Variance}.</p>
*/
public void increment(final double d) {
if (incMoment) {
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
