You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by ps...@apache.org on 2004/07/04 11:02:36 UTC
cvs commit: jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/summary Product.java Sum.java SumOfLogs.java SumOfSquares.java
psteitz 2004/07/04 02:02:36
Modified: math/src/java/org/apache/commons/math/stat/univariate
AbstractUnivariateStatistic.java
UnivariateStatistic.java
math/src/java/org/apache/commons/math/stat/univariate/moment
FirstMoment.java FourthMoment.java
GeometricMean.java Kurtosis.java Mean.java
SecondMoment.java Skewness.java
StandardDeviation.java ThirdMoment.java
Variance.java
math/src/java/org/apache/commons/math/stat/univariate/rank
Max.java Median.java Min.java Percentile.java
math/src/java/org/apache/commons/math/stat/univariate/summary
Product.java Sum.java SumOfLogs.java
SumOfSquares.java
Log:
javadoc
Revision Changes Path
1.19 +25 -14 jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/AbstractUnivariateStatistic.java
Index: AbstractUnivariateStatistic.java
===================================================================
RCS file: /home/cvs/jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/AbstractUnivariateStatistic.java,v
retrieving revision 1.18
retrieving revision 1.19
diff -u -r1.18 -r1.19
--- AbstractUnivariateStatistic.java 23 Jun 2004 16:26:16 -0000 1.18
+++ AbstractUnivariateStatistic.java 4 Jul 2004 09:02:36 -0000 1.19
@@ -18,9 +18,16 @@
import java.io.Serializable;
/**
- * Abstract Implementation for UnivariateStatistics.
- * Provides the ability to extend polymophically so that
- * indiviual statistics do not need to implement these methods.
+ * Abstract base class for all implementations of the
+ * {@link UnivariateStatistic} interface.
+ * <p>
+ * Provides a default implementation of <code>evaluate(double[]),</code>
+ * delegating to <code>evaluate(double[], int, int)</code> in the natural way.
+ * <p>
+ * Also includes a <code>test</code> method that performs generic parameter
+ * validation for the <code>evaluate</code> methods.
+ * <p>
+ *
* @version $Revision$ $Date$
*/
public abstract class AbstractUnivariateStatistic
@@ -40,19 +47,23 @@
/**
* @see org.apache.commons.math.stat.univariate.UnivariateStatistic#evaluate(double[], int, int)
*/
- public abstract double evaluate(
- final double[] values,
- final int begin,
- final int length);
+ public abstract double evaluate(final double[] values, final int begin, final int length);
/**
- * This method is used by all evaluation methods to verify that the content
- * of the array and indices are correct.
+ * This method is used by <code>evaluate(double[], int, int)</code> methods
+ * to verify that the input parameters designate a subarray of positive length.
* <p>
- * It is used by an individual statistic to determine if calculation
- * should continue, or return <code>Double.NaN</code> </p>
- * @param values Is a double[] containing the values
- * @param begin processing at this point in the array
+ * <ul>
+ * <li>returns <code>true</code> iff the parameters designate a subarray of
+ * positive length</li>
+ * <li>throws <code>IllegalArgumentException</code> if the array is null or
+ * or the indices are invalid</li>
+ * <li>returns <code>false</li> if the array is non-null, but
+ * <code>length</code> is 0.
+ * </ul>
+ *
+ * @param values the input array
+ * @param begin index of the first array element to include
* @param length the number of elements to include
* @return true if the parameters are valid and designate a subarray of positive length
* @throws IllegalArgumentException if the indices are invalid or the array is null
1.15 +17 -15 jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/UnivariateStatistic.java
Index: UnivariateStatistic.java
===================================================================
RCS file: /home/cvs/jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/UnivariateStatistic.java,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -r1.14 -r1.15
--- UnivariateStatistic.java 23 Jun 2004 16:26:16 -0000 1.14
+++ UnivariateStatistic.java 4 Jul 2004 09:02:36 -0000 1.15
@@ -16,30 +16,32 @@
package org.apache.commons.math.stat.univariate;
/**
- * UnivariateStatistic interface provides methods to evaluate
- * double[] based content using an implemented statistical approach.
- * The interface provides two "stateless" simple methods to calculate
- * a statistic from a double[] based parameter.
+ * Base evaluation interface implemented by all statistics.
+ * <p>
+ * Includes "stateless" <code>evaluate</code> methods that take
+ * <code>double[]</code> arrays as input and return the value of the statistic
+ * applied to the input values.
+ *
* @version $Revision$ $Date$
*/
public interface UnivariateStatistic {
/**
- * Evaluates the double[] returning the result of the evaluation.
- * @param values Is a double[] containing the values
- * @return the result of the evaluation or Double.NaN
- * if the array is empty
+ * Returns the result of evaluating the statistic over the input array.
+ *
+ * @param values input array
+ * @return the value of the statistic applied to the input array
*/
double evaluate(double[] values);
/**
- * 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
+ * Returns the result of evaluating the statistic over the specified entries
+ * in the input array.
+ *
+ * @param values the input array
+ * @param begin the index of the first element to include
* @param length the number of elements to include
- * @return the result of the evaluation or Double.NaN
- * if the array is empty
+ * @return the value of the statistic applied to the included array entries
*/
double evaluate(double[] values, int begin, int length);
1.18 +8 -2 jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/moment/FirstMoment.java
Index: FirstMoment.java
===================================================================
RCS file: /home/cvs/jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/moment/FirstMoment.java,v
retrieving revision 1.17
retrieving revision 1.18
diff -u -r1.17 -r1.18
--- FirstMoment.java 29 Jun 2004 02:14:17 -0000 1.17
+++ FirstMoment.java 4 Jul 2004 09:02:36 -0000 1.18
@@ -36,10 +36,16 @@
* </ol>
* <p>
* Returns <code>Double.NaN</code> if the dataset is empty.
+ * <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$ $Date$
*/
-public class FirstMoment extends AbstractStorelessUnivariateStatistic implements Serializable{
+public class FirstMoment extends AbstractStorelessUnivariateStatistic
+ implements Serializable {
/** Serializable version identifier */
static final long serialVersionUID = -803343206421984070L;
1.20 +6 -1 jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/moment/FourthMoment.java
Index: FourthMoment.java
===================================================================
RCS file: /home/cvs/jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/moment/FourthMoment.java,v
retrieving revision 1.19
retrieving revision 1.20
diff -u -r1.19 -r1.20
--- FourthMoment.java 29 Jun 2004 02:14:17 -0000 1.19
+++ FourthMoment.java 4 Jul 2004 09:02:36 -0000 1.20
@@ -41,6 +41,11 @@
* <p>
* Returns <code>Double.NaN</code> if no data values have been added and
* returns <code>0</code> if there is just one value in the data set.
+ * <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$ $Date$
*/
1.21 +19 -7 jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/moment/GeometricMean.java
Index: GeometricMean.java
===================================================================
RCS file: /home/cvs/jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/moment/GeometricMean.java,v
retrieving revision 1.20
retrieving revision 1.21
diff -u -r1.20 -r1.21
--- GeometricMean.java 23 Jun 2004 16:26:15 -0000 1.20
+++ GeometricMean.java 4 Jul 2004 09:02:36 -0000 1.21
@@ -33,7 +33,12 @@
* <code>Double.NEGATIVE_INFINITY</code> are among the values, the result is
* <code>NaN.</code></li>
* </ul>
- *
+ * <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$ $Date$
*/
@@ -73,13 +78,20 @@
}
/**
- * Returns the geometric mean for this collection of values
- * @param values Is a double[] containing the values
- * @param begin processing at this point in the array
+ * Returns the geometric mean of the entries in the specified portion
+ * of the input array.
+ * <p>
+ * See {@link GeometricMean} for details on the computing algorithm.
+ * <p>
+ * Throws <code>IllegalArgumentException</code> if the array is null.
+ *
+ * @param values input array containing the values
+ * @param begin first array element to include
* @param length the number of elements to include
- * @return the geometric mean or Double.NaN if the array is empty or
+ * @return the geometric mean or Double.NaN if length = 0 or
* any of the values are <= 0.
- * @see org.apache.commons.math.stat.univariate.UnivariateStatistic#evaluate(double[], int, int)
+ * @throws IllegalArgumentException if the input array is null or the array
+ * index parameters are not valid
*/
public double evaluate(
final double[] values,
1.25 +18 -8 jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/moment/Kurtosis.java
Index: Kurtosis.java
===================================================================
RCS file: /home/cvs/jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/moment/Kurtosis.java,v
retrieving revision 1.24
retrieving revision 1.25
diff -u -r1.24 -r1.25
--- Kurtosis.java 2 Jul 2004 05:29:14 -0000 1.24
+++ Kurtosis.java 4 Jul 2004 09:02:36 -0000 1.25
@@ -30,7 +30,12 @@
* <p>
* Note that this statistic is undefined for n < 4. <code>Double.Nan</code> is returned when
* there is not sufficient data to compute the statistic.
- *
+ * <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$ $Date$
*/
public class Kurtosis extends AbstractStorelessUnivariateStatistic implements Serializable {
@@ -121,15 +126,20 @@
/* UnvariateStatistic Approach */
/**
- * Returns the kurtosis for this collection of values.
+ * Returns the kurtosis of the entries in the specified portion of the
+ * input array.
* <p>
- * See {@link Kurtosis} for the definition used in the computation.
+ * See {@link Kurtosis} for details on the computing algorithm.
+ * <p>
+ * Throws <code>IllegalArgumentException</code> if the array is null.
*
- * @param values Is a double[] containing the values
- * @param begin processing at this point in the array
+ * @param values the input array
+ * @param begin index of the first array element to include
* @param length the number of elements to include
- * @return the kurtosis of the values or Double.NaN if the array is empty or has fewer than
- * four elements
+ * @return the kurtosis of the values or Double.NaN if length is less than
+ * 4
+ * @throws IllegalArgumentException if the input array is null or the array
+ * index parameters are not valid
*/
public double evaluate(final double[] values,final int begin, final int length) {
// Initialize the kurtosis
1.20 +11 -10 jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/moment/Mean.java
Index: Mean.java
===================================================================
RCS file: /home/cvs/jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/moment/Mean.java,v
retrieving revision 1.19
retrieving revision 1.20
diff -u -r1.19 -r1.20
--- Mean.java 2 Jul 2004 13:59:49 -0000 1.19
+++ Mean.java 4 Jul 2004 09:02:36 -0000 1.20
@@ -41,8 +41,8 @@
* <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.
+ * one of the threads invokes the <code>increment()</code> or
+ * <code>clear()</code> method, it must be synchronized externally.
*
* @version $Revision$ $Date$
*/
@@ -111,19 +111,20 @@
}
/**
- * Returns the arithmetic mean of the values in the input array, or
- * <code>Double.NaN</code> if the array is empty.
+ * Returns the arithmetic mean of the entries in the specified portion of
+ * the input array, or <code>Double.NaN</code> if the designated subarray
+ * is empty.
* <p>
* Throws <code>IllegalArgumentException</code> if the array is null.
* <p>
* See {@link Mean} for details on the computing algorithm.
*
- * @param values Is a double[] containing the values
- * @param begin processing at this point in the array
+ * @param values the input array
+ * @param begin index of the first array element to include
* @param length the number of elements to include
- * @return the mean of the values or Double.NaN if the array is empty
- * @throws IllegalArgumentException if the array is null
- * @see org.apache.commons.math.stat.univariate.UnivariateStatistic#evaluate(double[], int, int)
+ * @return the mean of the values or Double.NaN if length = 0
+ * @throws IllegalArgumentException if the array is null or the array index
+ * parameters are not valid
*/
public double evaluate(final double[] values,final int begin, final int length) {
if (test(values, begin, length)) {
1.19 +6 -1 jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/moment/SecondMoment.java
Index: SecondMoment.java
===================================================================
RCS file: /home/cvs/jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/moment/SecondMoment.java,v
retrieving revision 1.18
retrieving revision 1.19
diff -u -r1.18 -r1.19
--- SecondMoment.java 29 Jun 2004 02:14:17 -0000 1.18
+++ SecondMoment.java 4 Jul 2004 09:02:36 -0000 1.19
@@ -33,6 +33,11 @@
* <p>
* Returns <code>Double.NaN</code> if no data values have been added and
* returns <code>0</code> if there is just one value in the data set.
+ * <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$ $Date$
*/
1.24 +23 -15 jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/moment/Skewness.java
Index: Skewness.java
===================================================================
RCS file: /home/cvs/jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/moment/Skewness.java,v
retrieving revision 1.23
retrieving revision 1.24
diff -u -r1.23 -r1.24
--- Skewness.java 2 Jul 2004 05:29:14 -0000 1.23
+++ Skewness.java 4 Jul 2004 09:02:36 -0000 1.24
@@ -23,12 +23,17 @@
* Computes the skewness of the available values.
* <p>
* We use the following (unbiased) formula to define skewness:
- * <p>
- * skewness = [n / (n -1) (n - 2)] sum[(x_i - mean)^3] / std^3
- * <p>
- * where n is the number of values, mean is the {@link Mean} and std is the
+ * <p>
+ * skewness = [n / (n -1) (n - 2)] sum[(x_i - mean)^3] / std^3
+ * <p>
+ * where n is the number of values, mean is the {@link Mean} and std is the
* {@link StandardDeviation}
- *
+ * <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$ $Date$
*/
public class Skewness extends AbstractStorelessUnivariateStatistic implements Serializable {
@@ -113,20 +118,23 @@
}
/**
- * Returns the Skewness of the values array.
+ * Returns the Skewness of the entries in the specifed portion of the
+ * input array.
* <p>
* See {@link Skewness} for the definition used in the computation.
+ * <p>
+ * Throws <code>IllegalArgumentException</code> if the array is null.
*
- * @param values Is a double[] containing the values
- * @param begin processing at this point in the array
+ * @param values the input array
+ * @param begin the index of the first array element to include
* @param length the number of elements to include
- * @return the skewness of the values or Double.NaN if the array is empty
- * @see org.apache.commons.math.stat.univariate.UnivariateStatistic#evaluate(double[], int, int)
+ * @return the skewness of the values or Double.NaN if length is less than
+ * 3
+ * @throws IllegalArgumentException if the array is null or the array index
+ * parameters are not valid
*/
- public double evaluate(
- final double[] values,
- final int begin,
- final int length) {
+ public double evaluate(final double[] values,final int begin,
+ final int length) {
// Initialize the skewness
double skew = Double.NaN;
1.19 +17 -8 jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/moment/StandardDeviation.java
Index: StandardDeviation.java
===================================================================
RCS file: /home/cvs/jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/moment/StandardDeviation.java,v
retrieving revision 1.18
retrieving revision 1.19
diff -u -r1.18 -r1.19
--- StandardDeviation.java 26 Jun 2004 22:41:27 -0000 1.18
+++ StandardDeviation.java 4 Jul 2004 09:02:36 -0000 1.19
@@ -21,7 +21,12 @@
* Computes the sample standard deviation. The standard deviation
* is the positive square root of the 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$ $Date$
*/
public class StandardDeviation extends Variance implements Serializable {
@@ -67,14 +72,18 @@
}
/**
- * Returns the Standard Deviation on an array of 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
+ * is empty.
+ * <p>
+ * Returns 0 for a single-value (i.e. length = 1) sample.
*
- * @param values Is a double[] containing the values
- * @param begin processing at this point in the array
+ * @param values the input array
+ * @param begin index of the first array element to include
* @param length the number of elements to include
- * @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)
+ * @return the standard deviation of the values or Double.NaN if length = 0
+ * @throws IllegalArgumentException if the array is null or the array index
+ * parameters are not valid
*/
public double evaluate(final double[] values, final int begin, final int length) {
return Math.sqrt(super.evaluate(values, begin, length));
1.19 +6 -1 jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/moment/ThirdMoment.java
Index: ThirdMoment.java
===================================================================
RCS file: /home/cvs/jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/moment/ThirdMoment.java,v
retrieving revision 1.18
retrieving revision 1.19
diff -u -r1.18 -r1.19
--- ThirdMoment.java 29 Jun 2004 02:14:17 -0000 1.18
+++ ThirdMoment.java 4 Jul 2004 09:02:36 -0000 1.19
@@ -34,6 +34,11 @@
* <p>
* Returns <code>Double.NaN</code> if no data values have been added and
* returns <code>0</code> if there is just one value in the data set.
+ * <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$ $Date$
*/
1.23 +22 -16 jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/moment/Variance.java
Index: Variance.java
===================================================================
RCS file: /home/cvs/jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/moment/Variance.java,v
retrieving revision 1.22
retrieving revision 1.23
diff -u -r1.22 -r1.23
--- Variance.java 27 Jun 2004 19:37:51 -0000 1.22
+++ Variance.java 4 Jul 2004 09:02:36 -0000 1.23
@@ -29,10 +29,15 @@
* <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">
+ * as described in <a href="http://doi.acm.org/10.1145/359146.359152">
* Chan, T. F. andJ. G. Lewis 1979, <i>Communications of the ACM</i>,
* vol. 22 no. 9, pp. 526-531.</a>.
- *
+* <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$ $Date$
*/
public class Variance extends AbstractStorelessUnivariateStatistic implements Serializable {
@@ -105,21 +110,22 @@
}
/**
- * 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:
+ * Returns the variance of the entries in the specified portion of
+ * the input array, or <code>Double.NaN</code> if the designated subarray
+ * is empty.
* <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
+ * See {@link Variance} for details on the computing algorithm.
+ * <p>
+ * Returns 0 for a single-value (i.e. length = 1) sample.
+ * <p>
+ * Throws <code>IllegalArgumentException</code> if the array is null.
+ *
+ * @param values the input array
+ * @param begin index of the first array element to include
* @param length the number of elements to include
- * @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)
+ * @return the variance of the values or Double.NaN if length = 0
+ * @throws IllegalArgumentException if the array is null or the array index
+ * parameters are not valid
*/
public double evaluate(final double[] values, final int begin, final int length) {
1.19 +26 -4 jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/rank/Max.java
Index: Max.java
===================================================================
RCS file: /home/cvs/jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/rank/Max.java,v
retrieving revision 1.18
retrieving revision 1.19
diff -u -r1.18 -r1.19
--- Max.java 23 Jun 2004 16:26:17 -0000 1.18
+++ Max.java 4 Jul 2004 09:02:36 -0000 1.19
@@ -28,7 +28,12 @@
* <li>If any of the values equals <code>Double.POSITIVE_INFINITY</code>,
* the result is <code>Double.POSITIVE_INFINITY.</code></li>
* </ul>
- *
+* <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$ $Date$
*/
public class Max extends AbstractStorelessUnivariateStatistic implements Serializable {
@@ -75,9 +80,26 @@
}
/**
- * Returns the maximum of the available values.
+ * Returns the maximum of the entries in the specified portion of
+ * the input array, or <code>Double.NaN</code> if the designated subarray
+ * is empty.
+ * <p>
+ * Throws <code>IllegalArgumentException</code> if the array is null or
+ * the array index parameters are not valid.
+ * <p>
+ * <ul>
+ * <li>The result is <code>NaN</code> iff all values are <code>NaN</code>
+ * (i.e. <code>NaN</code> values have no impact on the value of the statistic).</li>
+ * <li>If any of the values equals <code>Double.POSITIVE_INFINITY</code>,
+ * the result is <code>Double.POSITIVE_INFINITY.</code></li>
+ * </ul>
*
- * @see org.apache.commons.math.stat.univariate.UnivariateStatistic#evaluate(double[], int, int)
+ * @param values the input array
+ * @param begin index of the first array element to include
+ * @param length the number of elements to include
+ * @return the mean of the values or Double.NaN if length = 0
+ * @throws IllegalArgumentException if the array is null or the array index
+ * parameters are not valid
*/
public double evaluate(final double[] values, final int begin, final int length) {
double max = Double.NaN;
1.16 +7 -2 jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/rank/Median.java
Index: Median.java
===================================================================
RCS file: /home/cvs/jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/rank/Median.java,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -r1.15 -r1.16
--- Median.java 29 Jun 2004 05:42:51 -0000 1.15
+++ Median.java 4 Jul 2004 09:02:36 -0000 1.16
@@ -21,7 +21,12 @@
/**
* Returns the median of the available values. This is the same as the 50th percentile.
* See {@link Percentile} for a description of the algorithm used.
- *
+ * <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$ $Date$
*/
public class Median extends Percentile implements Serializable {
1.20 +26 -4 jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/rank/Min.java
Index: Min.java
===================================================================
RCS file: /home/cvs/jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/rank/Min.java,v
retrieving revision 1.19
retrieving revision 1.20
diff -u -r1.19 -r1.20
--- Min.java 23 Jun 2004 16:26:17 -0000 1.19
+++ Min.java 4 Jul 2004 09:02:36 -0000 1.20
@@ -28,7 +28,12 @@
* <li>If any of the values equals <code>Double.NEGATIVE_INFINITY</code>,
* the result is <code>Double.NEGATIVE_INFINITY.</code></li>
* </ul>
- *
+ * <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$ $Date$
*/
public class Min extends AbstractStorelessUnivariateStatistic implements Serializable {
@@ -75,9 +80,26 @@
}
/**
- * Returns the minimum of the available values.
+ * Returns the minimum of the entries in the specified portion of
+ * the input array, or <code>Double.NaN</code> if the designated subarray
+ * is empty.
+ * <p>
+ * Throws <code>IllegalArgumentException</code> if the array is null or
+ * the array index parameters are not valid.
+ * <p>
+ * <ul>
+ * <li>The result is <code>NaN</code> iff all values are <code>NaN</code>
+ * (i.e. <code>NaN</code> values have no impact on the value of the statistic).</li>
+ * <li>If any of the values equals <code>Double.NEGATIVE_INFINITY</code>,
+ * the result is <code>Double.NEGATIVE_INFINITY.</code></li>
+ * </ul>
*
- * @see org.apache.commons.math.stat.univariate.UnivariateStatistic#evaluate(double[], int, int)
+ * @param values the input array
+ * @param begin index of the first array element to include
+ * @param length the number of elements to include
+ * @return the mean of the values or Double.NaN if length = 0
+ * @throws IllegalArgumentException if the array is null or the array index
+ * parameters are not valid
*/
public double evaluate(final double[] values,final int begin, final int length) {
double min = Double.NaN;
1.22 +17 -12 jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/rank/Percentile.java
Index: Percentile.java
===================================================================
RCS file: /home/cvs/jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/rank/Percentile.java,v
retrieving revision 1.21
retrieving revision 1.22
diff -u -r1.21 -r1.22
--- Percentile.java 23 Jun 2004 16:26:17 -0000 1.21
+++ Percentile.java 4 Jul 2004 09:02:36 -0000 1.22
@@ -42,7 +42,6 @@
* </li>
* </ol>
* <p>
- *
* To compute percentiles, the data must be (totally) ordered. Input arrays
* are copied and then sorted using {@link java.util.Arrays#sort(double[])}.
* The ordering used by <code>Arrays.sort(double[]</code> is the one determined
@@ -55,7 +54,12 @@
* Since percentile estimation usually involves interpolation between array
* elements, arrays containing <code>NaN</code> or infinite values will often
* result in <code>NaN<code> or infinite values returned.
- *
+ * <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$ $Date$
*/
public class Percentile extends AbstractUnivariateStatistic implements Serializable {
@@ -102,10 +106,10 @@
* </ul>
* <p>
* See {@link Percentile} for a description of the percentile estimation
- * algorithm used.
+ * algorithm used.
*
- * @param values Is a double[] containing the values
- * @param p Is the quantile to evaluate to.
+ * @param values input array of values
+ * @param p the percentile value to compute
* @return the result of the evaluation or Double.NaN if the array is empty
* @throws IllegalArgumentException if <code>values</code> is null
*/
@@ -116,8 +120,8 @@
/**
* Returns an estimate of the <code>quantile</code>th percentile of the
- * values in the <code>values</code> array. The quantile estimated is
- * determined by the <code>quantile</code> property.
+ * designated values in the <code>values</code> array. The quantile
+ * estimated is determined by the <code>quantile</code> property.
* <p>
* <ul>
* <li>Returns <code>Double.NaN</code> if <code>length = 0</code></li>
@@ -131,9 +135,9 @@
* See {@link Percentile} for a description of the percentile estimation
* algorithm used.
*
- * @param values array of input values
- * @param start the first (0-based) element to include in the computation
- * @param length the number of array elements to include
+ * @param values the input array
+ * @param start index of the first array element to include
+ * @param length the number of elements to include
* @return the percentile value
* @throws IllegalArgumentException if the parameters are not valid
*
@@ -168,7 +172,8 @@
* @param begin the first (0-based) element to include in the computation
* @param length the number of array elements to include
* @return the percentile value
- * @throws IllegalArgumentException if the parameters are not valid
+ * @throws IllegalArgumentException if the parameters are not valid or the
+ * input array is null
*/
public double evaluate(final double[] values, final int begin,
final int length, final double p) {
1.20 +16 -6 jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/summary/Product.java
Index: Product.java
===================================================================
RCS file: /home/cvs/jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/summary/Product.java,v
retrieving revision 1.19
retrieving revision 1.20
diff -u -r1.19 -r1.20
--- Product.java 29 Jun 2004 06:06:13 -0000 1.19
+++ Product.java 4 Jul 2004 09:02:36 -0000 1.20
@@ -24,6 +24,11 @@
* <p>
* If there are no values in the dataset, or any of the values are
* <code>NaN</code>, then <code>NaN</code> is returned.
+* <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$ $Date$
*/
@@ -75,13 +80,18 @@
}
/**
- * Returns the product for this collection of values
+ * Returns the product of the entries in the specified portion of
+ * the input array, or <code>Double.NaN</code> if the designated subarray
+ * is empty.
+ * <p>
+ * Throws <code>IllegalArgumentException</code> if the array is null.
*
- * @param values Is a double[] containing the values
- * @param begin processing at this point in the array
+ * @param values the input array
+ * @param begin index of the first array element to include
* @param length the number of elements to include
- * @return the product values or Double.NaN if the array is empty
- * @see org.apache.commons.math.stat.univariate.UnivariateStatistic#evaluate(double[], int, int)
+ * @return the product of the values or Double.NaN if length = 0
+ * @throws IllegalArgumentException if the array is null or the array index
+ * parameters are not valid
*/
public double evaluate(final double[] values, final int begin, final int length) {
double product = Double.NaN;
1.23 +16 -6 jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/summary/Sum.java
Index: Sum.java
===================================================================
RCS file: /home/cvs/jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/summary/Sum.java,v
retrieving revision 1.22
retrieving revision 1.23
diff -u -r1.22 -r1.23
--- Sum.java 29 Jun 2004 15:39:15 -0000 1.22
+++ Sum.java 4 Jul 2004 09:02:36 -0000 1.23
@@ -24,6 +24,11 @@
* <p>
* If there are no values in the dataset, or any of the values are
* <code>NaN</code>, then <code>NaN</code> is returned.
+ * <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$ $Date$
*/
@@ -75,13 +80,18 @@
}
/**
- * The sum of the values that have been added.
+ * The sum of the entries in the specified portion of
+ * the input array, or <code>Double.NaN</code> if the designated subarray
+ * is empty.
+ * <p>
+ * Throws <code>IllegalArgumentException</code> if the array is null.
*
- * @param values Is a double[] containing the values
- * @param begin processing at this point in the array
+ * @param values the input array
+ * @param begin index of the first array element to include
* @param length the number of elements to include
- * @return the sum of the values or Double.NaN if the array is empty
- * @see org.apache.commons.math.stat.univariate.UnivariateStatistic#evaluate(double[], int, int)
+ * @return the sum of the values or Double.NaN if length = 0
+ * @throws IllegalArgumentException if the array is null or the array index
+ * parameters are not valid
*/
public double evaluate(final double[] values, final int begin, final int length) {
double sum = Double.NaN;
1.20 +18 -7 jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/summary/SumOfLogs.java
Index: SumOfLogs.java
===================================================================
RCS file: /home/cvs/jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/summary/SumOfLogs.java,v
retrieving revision 1.19
retrieving revision 1.20
diff -u -r1.19 -r1.20
--- SumOfLogs.java 23 Jun 2004 16:26:16 -0000 1.19
+++ SumOfLogs.java 4 Jul 2004 09:02:36 -0000 1.20
@@ -31,7 +31,12 @@
* <code>Double.NEGATIVE_INFINITY</code> are among the values, the result is
* <code>NaN.</code></li>
* </ul>
- *
+ * <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$ $Date$
*/
public class SumOfLogs extends AbstractStorelessUnivariateStatistic implements Serializable {
@@ -82,15 +87,21 @@
}
/**
- * Returns the sum of the natural logs for this collection of values.
+ * Returns the sum of the natural logs of the entries in the specified portion of
+ * the input array, or <code>Double.NaN</code> if the designated subarray
+ * is empty.
+ * <p>
+ * Throws <code>IllegalArgumentException</code> if the array is null.
* <p>
* See {@link SumOfLogs}.
*
- * @param values Is a double[] containing the values
- * @param begin processing at this point in the array
+ * @param values the input array
+ * @param begin index of the first array element to include
* @param length the number of elements to include
- * @return the sumLog value or Double.NaN if the array is empty
- * @see org.apache.commons.math.stat.univariate.UnivariateStatistic#evaluate(double[], int, int)
+ * @return the sum of the natural logs of the values or Double.NaN if
+ * length = 0
+ * @throws IllegalArgumentException if the array is null or the array index
+ * parameters are not valid
*/
public double evaluate(final double[] values, final int begin, final int length) {
double sumLog = Double.NaN;
1.20 +16 -6 jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/summary/SumOfSquares.java
Index: SumOfSquares.java
===================================================================
RCS file: /home/cvs/jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/summary/SumOfSquares.java,v
retrieving revision 1.19
retrieving revision 1.20
diff -u -r1.19 -r1.20
--- SumOfSquares.java 29 Jun 2004 15:39:15 -0000 1.19
+++ SumOfSquares.java 4 Jul 2004 09:02:36 -0000 1.20
@@ -24,6 +24,11 @@
* <p>
* If there are no values in the dataset, or any of the values are
* <code>NaN</code>, then <code>NaN</code> is returned.
+ * <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$ $Date$
*/
@@ -75,13 +80,18 @@
}
/**
- * Returns the sum of the squares of the available values.
+ * Returns the sum of the squares of the entries in the specified portion of
+ * the input array, or <code>Double.NaN</code> if the designated subarray
+ * is empty.
+ * <p>
+ * Throws <code>IllegalArgumentException</code> if the array is null.
*
- * @param values Is a double[] containing the values
- * @param begin processing at this point in the array
+ * @param values the input array
+ * @param begin index of the first array element to include
* @param length the number of elements to include
- * @return the sum of the squared values or Double.NaN if the array is empty
- * @see org.apache.commons.math.stat.univariate.UnivariateStatistic#evaluate(double[], int, int)
+ * @return the sum of the squares of the values or Double.NaN if length = 0
+ * @throws IllegalArgumentException if the array is null or the array index
+ * parameters are not valid
*/
public double evaluate(final double[] values,final int begin, final int length) {
double sumSq = Double.NaN;
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org