Return-Path: Delivered-To: apmail-jakarta-commons-dev-archive@www.apache.org Received: (qmail 13579 invoked from network); 4 Jul 2004 09:10:17 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (209.237.227.199) by minotaur-2.apache.org with SMTP; 4 Jul 2004 09:10:17 -0000 Received: (qmail 67707 invoked by uid 500); 4 Jul 2004 09:10:21 -0000 Delivered-To: apmail-jakarta-commons-dev-archive@jakarta.apache.org Received: (qmail 67475 invoked by uid 500); 4 Jul 2004 09:10:15 -0000 Mailing-List: contact commons-dev-help@jakarta.apache.org; run by ezmlm Precedence: bulk List-Unsubscribe: List-Subscribe: List-Help: List-Post: List-Id: "Jakarta Commons Developers List" Reply-To: "Jakarta Commons Developers List" Delivered-To: mailing list commons-dev@jakarta.apache.org Received: (qmail 67422 invoked by uid 500); 4 Jul 2004 09:10:14 -0000 Received: (qmail 67355 invoked by uid 99); 4 Jul 2004 09:10:11 -0000 X-ASF-Spam-Status: No, hits=0.5 required=10.0 tests=ALL_TRUSTED,NO_REAL_NAME X-Spam-Check-By: apache.org Received: from [209.237.227.194] (HELO minotaur.apache.org) (209.237.227.194) by apache.org (qpsmtpd/0.27.1) with SMTP; Sun, 04 Jul 2004 02:10:07 -0700 Received: (qmail 10944 invoked by uid 1718); 4 Jul 2004 09:02:36 -0000 Date: 4 Jul 2004 09:02:36 -0000 Message-ID: <20040704090236.10943.qmail@minotaur.apache.org> From: psteitz@apache.org To: jakarta-commons-cvs@apache.org Subject: cvs commit: jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/summary Product.java Sum.java SumOfLogs.java SumOfSquares.java X-Virus-Checked: Checked X-Spam-Rating: minotaur-2.apache.org 1.6.2 0/1000/N 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. + *

+ * Provides a default implementation of evaluate(double[]), + * delegating to evaluate(double[], int, int) in the natural way. + *

+ * Also includes a test method that performs generic parameter + * validation for the evaluate methods. + *

+ * * @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 evaluate(double[], int, int) methods + * to verify that the input parameters designate a subarray of positive length. *

- * It is used by an individual statistic to determine if calculation - * should continue, or return Double.NaN

- * @param values Is a double[] containing the values - * @param begin processing at this point in the array + *
    + *
  • returns true iff the parameters designate a subarray of + * positive length
    • + *
  • throws IllegalArgumentException if the array is null or + * or the indices are invalid
    • + *
  • returns false
    • if the array is non-null, but + * length is 0. + *
+ * + * @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. + *

+ * Includes "stateless" evaluate methods that take + * double[] 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 @@ * *

* Returns Double.NaN if the dataset is empty. + *

+ * Note that this implementation is not synchronized. If + * multiple threads access an instance of this class concurrently, and at least + * one of the threads invokes the increment() or + * clear() 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 @@ *

* Returns Double.NaN if no data values have been added and * returns 0 if there is just one value in the data set. + *

+ * Note that this implementation is not synchronized. If + * multiple threads access an instance of this class concurrently, and at least + * one of the threads invokes the increment() or + * clear() 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 @@ * Double.NEGATIVE_INFINITY are among the values, the result is * NaN. * - * + *

+ * Note that this implementation is not synchronized. If + * multiple threads access an instance of this class concurrently, and at least + * one of the threads invokes the increment() or + * clear() 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. + *

+ * See {@link GeometricMean} for details on the computing algorithm. + *

+ * Throws IllegalArgumentException 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 @@ *

* Note that this statistic is undefined for n < 4. Double.Nan is returned when * there is not sufficient data to compute the statistic. - * + *

+ * Note that this implementation is not synchronized. If + * multiple threads access an instance of this class concurrently, and at least + * one of the threads invokes the increment() or + * clear() 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. *

- * See {@link Kurtosis} for the definition used in the computation. + * See {@link Kurtosis} for details on the computing algorithm. + *

+ * Throws IllegalArgumentException 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 @@ *

* Note that this implementation is not synchronized. If * multiple threads access an instance of this class concurrently, and at least - * one of the threads invokes the increment(), or - * clear() method, it must be synchronized externally. + * one of the threads invokes the increment() or + * clear() 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 - * Double.NaN if the array is empty. + * Returns the arithmetic mean of the entries in the specified portion of + * the input array, or Double.NaN if the designated subarray + * is empty. *

* Throws IllegalArgumentException if the array is null. *

* 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 @@ *

* Returns Double.NaN if no data values have been added and * returns 0 if there is just one value in the data set. + *

+ * Note that this implementation is not synchronized. If + * multiple threads access an instance of this class concurrently, and at least + * one of the threads invokes the increment() or + * clear() 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. *

* We use the following (unbiased) formula to define skewness: - *

- * skewness = [n / (n -1) (n - 2)] sum[(x_i - mean)^3] / std^3 - *

- * where n is the number of values, mean is the {@link Mean} and std is the + *

+ * skewness = [n / (n -1) (n - 2)] sum[(x_i - mean)^3] / std^3 + *

+ * where n is the number of values, mean is the {@link Mean} and std is the * {@link StandardDeviation} - * + *

+ * Note that this implementation is not synchronized. If + * multiple threads access an instance of this class concurrently, and at least + * one of the threads invokes the increment() or + * clear() 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. *

* See {@link Skewness} for the definition used in the computation. + *

+ * Throws IllegalArgumentException 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. - * + *

+ * Note that this implementation is not synchronized. If + * multiple threads access an instance of this class concurrently, and at least + * one of the threads invokes the increment() or + * clear() 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 Double.NaN if the designated subarray + * is empty. + *

+ * 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 @@ *

* Returns Double.NaN if no data values have been added and * returns 0 if there is just one value in the data set. + *

+ * Note that this implementation is not synchronized. If + * multiple threads access an instance of this class concurrently, and at least + * one of the threads invokes the increment() or + * clear() 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 @@ *

* The definitional formula does not have good numerical properties, so * this implementation uses updating formulas based on West's algorithm - * as described in + * as described in * Chan, T. F. andJ. G. Lewis 1979, Communications of the ACM, * vol. 22 no. 9, pp. 526-531.. - * +*

+ * Note that this implementation is not synchronized. If + * multiple threads access an instance of this class concurrently, and at least + * one of the threads invokes the increment() or + * clear() 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 - * - * corrected two pass formula (14.1.8), and also referenced in: + * Returns the variance of the entries in the specified portion of + * the input array, or Double.NaN if the designated subarray + * is empty. *

- * "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. - *

- * @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. + *

+ * Returns 0 for a single-value (i.e. length = 1) sample. + *

+ * Throws IllegalArgumentException 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 @@ *

  • If any of the values equals Double.POSITIVE_INFINITY, * the result is Double.POSITIVE_INFINITY.
    • * - * +*

    + * Note that this implementation is not synchronized. If + * multiple threads access an instance of this class concurrently, and at least + * one of the threads invokes the increment() or + * clear() 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 Double.NaN if the designated subarray + * is empty. + *

    + * Throws IllegalArgumentException if the array is null or + * the array index parameters are not valid. + *

    + *

      + *
    • The result is NaN iff all values are NaN + * (i.e. NaN values have no impact on the value of the statistic).
      • + *
    • If any of the values equals Double.POSITIVE_INFINITY, + * the result is Double.POSITIVE_INFINITY.
      • + *
    * - * @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. - * + *

    + * Note that this implementation is not synchronized. If + * multiple threads access an instance of this class concurrently, and at least + * one of the threads invokes the increment() or + * clear() 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 @@ *

  • If any of the values equals Double.NEGATIVE_INFINITY, * the result is Double.NEGATIVE_INFINITY.
    • * - * + *

    + * Note that this implementation is not synchronized. If + * multiple threads access an instance of this class concurrently, and at least + * one of the threads invokes the increment() or + * clear() 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 Double.NaN if the designated subarray + * is empty. + *

    + * Throws IllegalArgumentException if the array is null or + * the array index parameters are not valid. + *

    + *

      + *
    • The result is NaN iff all values are NaN + * (i.e. NaN values have no impact on the value of the statistic).
      • + *
    • If any of the values equals Double.NEGATIVE_INFINITY, + * the result is Double.NEGATIVE_INFINITY.
      • + *
    * - * @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 @@ * * *

    - * * 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 Arrays.sort(double[] is the one determined @@ -55,7 +54,12 @@ * Since percentile estimation usually involves interpolation between array * elements, arrays containing NaN or infinite values will often * result in NaN or infinite values returned. - * + *

    + * Note that this implementation is not synchronized. If + * multiple threads access an instance of this class concurrently, and at least + * one of the threads invokes the increment() or + * clear() method, it must be synchronized externally. + * * @version $Revision$ $Date$ */ public class Percentile extends AbstractUnivariateStatistic implements Serializable { @@ -102,10 +106,10 @@ * *

    * 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 values is null */ @@ -116,8 +120,8 @@ /** * Returns an estimate of the quantileth percentile of the - * values in the values array. The quantile estimated is - * determined by the quantile property. + * designated values in the values array. The quantile + * estimated is determined by the quantile property. *

    *

      *
    • Returns Double.NaN if length = 0
      • @@ -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 @@ *

      * If there are no values in the dataset, or any of the values are * NaN, then NaN is returned. +*

      + * Note that this implementation is not synchronized. If + * multiple threads access an instance of this class concurrently, and at least + * one of the threads invokes the increment() or + * clear() 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 Double.NaN if the designated subarray + * is empty. + *

      + * Throws IllegalArgumentException 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 @@ *

      * If there are no values in the dataset, or any of the values are * NaN, then NaN is returned. + *

      + * Note that this implementation is not synchronized. If + * multiple threads access an instance of this class concurrently, and at least + * one of the threads invokes the increment() or + * clear() 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 Double.NaN if the designated subarray + * is empty. + *

      + * Throws IllegalArgumentException 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 @@ * Double.NEGATIVE_INFINITY are among the values, the result is * NaN. *

    - * + *

    + * Note that this implementation is not synchronized. If + * multiple threads access an instance of this class concurrently, and at least + * one of the threads invokes the increment() or + * clear() 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 Double.NaN if the designated subarray + * is empty. + *

    + * Throws IllegalArgumentException if the array is null. *

    * 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 @@ *

    * If there are no values in the dataset, or any of the values are * NaN, then NaN is returned. + *

    + * Note that this implementation is not synchronized. If + * multiple threads access an instance of this class concurrently, and at least + * one of the threads invokes the increment() or + * clear() 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 Double.NaN if the designated subarray + * is empty. + *

    + * Throws IllegalArgumentException 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