javadoc.

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

src/java/org/apache/commons/math/stat/AbstractDescriptiveStatistics.java

@@ -1,7 +1,7 @@
 /* ====================================================================
  * The Apache Software License, Version 1.1
  *
- * Copyright (c) 2003 The Apache Software Foundation.  All rights
+ * Copyright (c) 2003-2004 The Apache Software Foundation.  All rights
  * reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -58,8 +58,9 @@ import java.util.Arrays;
 import org.apache.commons.math.stat.univariate.rank.Percentile;
 
 /**
- * Provides univariate measures for an array of doubles. 
+ * Extends {@link AbstractStorelessDescriptiveStatistics} to include univariate statistics
- * @version $Revision: 1.1 $ $Date: 2003/11/15 16:01:37 $
+ * that may require access to the full set of sample values. 
+ * @version $Revision: 1.2 $ $Date: 2004/01/18 03:45:02 $
  */
 public abstract class AbstractDescriptiveStatistics
     extends AbstractStorelessDescriptiveStatistics {

src/java/org/apache/commons/math/stat/AbstractStorelessDescriptiveStatistics.java

@@ -1,7 +1,7 @@
 /* ====================================================================
  * The Apache Software License, Version 1.1
  *
- * Copyright (c) 2003 The Apache Software Foundation.  All rights
+ * Copyright (c) 2003-2004 The Apache Software Foundation.  All rights
  * reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -67,8 +67,10 @@ import org.apache.commons.math.stat.univariate.summary.SumOfLogs;
 import org.apache.commons.math.stat.univariate.summary.SumOfSquares;
 
 /**
- * Provides univariate measures for an array of doubles.
+ * Provides a default {@link DescriptiveStatistics} implementation, including only statistics
- * @version $Revision: 1.1 $ $Date: 2003/11/15 16:01:37 $  
+ * that can be computed in one pass through the data without storing the full set of sample
+ * data values.
+ * @version $Revision: 1.2 $ $Date: 2004/01/18 03:45:02 $  
  */
 public abstract class AbstractStorelessDescriptiveStatistics extends DescriptiveStatistics {
 

src/java/org/apache/commons/math/stat/DescriptiveStatistics.java

@@ -1,7 +1,7 @@
 /* ====================================================================
  * The Apache Software License, Version 1.1
  *
- * Copyright (c) 2003 The Apache Software Foundation.  All rights
+ * Copyright (c) 2003-2004 The Apache Software Foundation.  All rights
  * reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -58,13 +58,9 @@ import java.io.Serializable;
 import org.apache.commons.discovery.tools.DiscoverClass;
 
 /**
- * DescriptiveStatistics implements the Univariate interface 
+ * Abstract factory class for univariate statistical summaries.
- * but maintains the set of values which contribute to 
+ * 
- * the values being returned.  This implementation of 
+ * @version $Revision: 1.3 $ $Date: 2004/01/18 03:45:02 $
- * Univariate provides additional percentile functionality 
- * such as.  This additional functionality comes with 
- * a price of increased storage costs.
- * @version $Revision: 1.2 $ $Date: 2003/11/19 03:28:23 $
  */
 public abstract class DescriptiveStatistics implements Serializable{
 

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

@@ -1,7 +1,7 @@
 /* ====================================================================
  * The Apache Software License, Version 1.1
  *
- * Copyright (c) 2003 The Apache Software Foundation.  All rights
+ * Copyright (c) 2003-2004 The Apache Software Foundation.  All rights
  * reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -59,17 +59,15 @@ package org.apache.commons.math.stat.univariate;
  * Provides the ability to extend polymophically so that
  * indiviual statistics do not need to implement these methods unless
  * there are better algorithms for handling the calculation.
- * @version $Revision: 1.11 $ $Date: 2003/11/14 22:22:21 $
+ * @version $Revision: 1.12 $ $Date: 2004/01/18 03:45:02 $
  */
 public abstract class AbstractStorelessUnivariateStatistic
     extends AbstractUnivariateStatistic
     implements StorelessUnivariateStatistic {
 
     /**
-     * This implements the AbstractUnivariateStatistic impl to funnel
+     * This default implementation just calls {@link #increment} in a loop and then {@link #getResult} to
-     * calculation off to the instantanious increment method. In most cases of
+     * compute the return value.  Most implementations will override this method with a more efficient implementation.
-     * StorelessUnivariateStatistic this is never really used because more
-     * efficient algorithms are available for that statistic.
      * @see org.apache.commons.math.stat.univariate.UnivariateStatistic#evaluate(double[], int, int)
      */
     public double evaluate(

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

@@ -1,7 +1,7 @@
 /* ====================================================================
  * The Apache Software License, Version 1.1
  *
- * Copyright (c) 2003 The Apache Software Foundation.  All rights
+ * Copyright (c) 2003-2004 The Apache Software Foundation.  All rights
  * reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -57,14 +57,12 @@ package org.apache.commons.math.stat.univariate;
  * Abstract Implementation for UnivariateStatistics.
  * Provides the ability to extend polymophically so that
  * indiviual statistics do not need to implement these methods.
- * @version $Revision: 1.10 $ $Date: 2003/11/14 22:22:21 $
+ * @version $Revision: 1.11 $ $Date: 2004/01/18 03:45:02 $
  */
 public abstract class AbstractUnivariateStatistic
     implements UnivariateStatistic {
 
     /**
-     * This implementation provides a simple wrapper around the double[]
-     * and passes the request onto the evaluate(DoubleArray da) method.
      * @see org.apache.commons.math.stat.univariate.UnivariateStatistic#evaluate(double[])
      */
     public double evaluate(final double[] values) {
@@ -72,7 +70,6 @@ public abstract class AbstractUnivariateStatistic
     }
 
     /**
-     * Subclasses of AbstractUnivariateStatistc need to implement this method.
      * @see org.apache.commons.math.stat.univariate.UnivariateStatistic#evaluate(double[], int, int)
      */
     public abstract double evaluate(
@@ -81,14 +78,16 @@ public abstract class AbstractUnivariateStatistic
         final int length);
 
     /**
-     * this protected test method used by all methods to verify the content
+     * This method is used by all evaluation methods to verify that the content
-     * of the array and indicies are correct.
+     * of the array and indices are correct.
+     * <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
      * @param length processing at this point in the array
-     * @return this is used to determine if the array is of 0 length or not,
+     * @return true if the array has postive length
-     * it is used by an individual statistic to determine if continuation
+     * @throws IllegalArgumentException if the indices are invalid or the array is null
-     * of a statistical calculation should continue or return NaN.
      */
     protected boolean test(
         final double[] values,

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

@@ -1,7 +1,7 @@
 /* ====================================================================
  * The Apache Software License, Version 1.1
  *
- * Copyright (c) 2003 The Apache Software Foundation.  All rights
+ * Copyright (c) 2003-2004 The Apache Software Foundation.  All rights
  * reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -54,38 +54,31 @@
 package org.apache.commons.math.stat.univariate;
 
 /**
- * Extends the capabilities of UnivariateStatistic with a statefull incremental
+ * Extends the definition of {@link UnivariateStatistic} with an {@link #increment}
- * strategy through three methods for calculating a statistic without having to
+ * method for adding values and updating internal state incrementally.  This interface
- * maintain a double[] of the values. Because a StorelessUnivariateStatistic
+ * is designed to be used for calculating statistics that can be computed in one pass through
- * does not require that a double[] storage structure be maintained with the
+ * the data without storing the full array of sample values.
- * values in it, there are only a subset of known statistics can actually be
+ * 
- * implemented using it. If a Statistic cannot be implemented in a Storeless
+ * @version $Revision: 1.13 $ $Date: 2004/01/18 03:45:02 $
- * approach it should implement the UnivariateStatistic interface directly
- * instead.
- * @version $Revision: 1.12 $ $Date: 2003/11/19 03:28:25 $
  */
 public interface StorelessUnivariateStatistic extends UnivariateStatistic {
 
     /**
-     * Increments the internal state of the Storagless
+     * Updates the internal state of the statistic to reflect the addition of the new value.
-     * Implementation.
+     * @param d  the new value.
-     * @param d is the value to increment the state by.
      */
     void increment(double d);
 
     /**
-     * Returns the current state of the statistic after the
+     * Returns the current value of the Statistic.
-     * last increment.
+     * @return value of the statistic, <code>Double.NaN</code> if it
-     * @return value of the statistic, Double.NaN if it
      * has been cleared or just instantiated.
      */
     double getResult();
 
     /**
-     * Returns the current state of the statistic after the
+     * Returns the number of values that have been added.
-     * last increment.
+     * @return the number of values.
-     * @return value of the statistic, Double.NaN if it
-     * has been cleared or just instantiated.
      */
     double getN();