Renamed internal field, added algorithm documentation.

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

src/java/org/apache/commons/math/stat/univariate/rank/Percentile.java

@@ -20,38 +20,51 @@ import java.util.Arrays;
 import org.apache.commons.math.stat.univariate.AbstractUnivariateStatistic;
 
 /**
- * @version $Revision: 1.14 $ $Date: 2004/03/04 04:25:09 $
+ * Provides percentile computation.
+ * <p>
+ * There are several commonly used methods for estimating percentiles (a.k.a. quantiles) based
+ * on sample data.  For large samples, the different methods agree closely, but when sample sizes
+ * are small, different methods will give significantly different results.  The implementation provided here
+ * follows the first estimation procedure presented
+ * <a href="http://www.itl.nist.gov/div898/handbook/prc/section2/prc252.htm">here.</a>
+ * 
+ * @version $Revision: 1.15 $ $Date: 2004/03/13 20:02:28 $
  */
 public class Percentile extends AbstractUnivariateStatistic implements Serializable {
 
     static final long serialVersionUID = -8091216485095130416L; 
        
-    /** */
+    /** Determines what percentile is computed when evaluate() is activated with no quantile argument */
-    private double percentile = 0.0;
+    private double quantile = 0.0;
 
     /**
-     * Constructs a Percentile with a default percentile
+     * Constructs a Percentile with a default quantile
      * value of 50.0.
      */
     public Percentile() {
         super();
-        percentile = 50.0;
+        quantile = 50.0;
     }
 
     /**
-     * Constructs a Percentile with the specific percentile value.
+     * Constructs a Percentile with the specific quantile value.
-     * @param p the percentile
+     * @param p the quantile
      */
     public Percentile(final double p) {
-        this.percentile = p;
+        this.quantile = p;
     }
 
     /**
-     * Evaluates the double[] top the specified percentile.
+     * Returns an estimate of the <code>p</code>th percentile of the values
-     * This does not alter the interal percentile state of the
+     * in the <code>values</code> array.
-     * statistic.
+     * <p>
+     * Calls to this method do not modify the internal <code>quantile</code>
+     * state of this statistic.
+     * <p>
+     * See {@link Percentile} for a description of the percentile estimation algorithm used.
+     * 
      * @param values Is a double[] containing the values
-     * @param p Is the percentile to evaluate to.
+     * @param p Is the quantile to evaluate to.
      * @return the result of the evaluation or Double.NaN
      * if the array is empty
      */
@@ -60,24 +73,42 @@ public class Percentile extends AbstractUnivariateStatistic implements Serializa
     }
 
     /**
-     * @see org.apache.commons.math.stat.univariate.UnivariateStatistic#evaluate(double[], int, int)
+     * 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.
+     * <p>
+     * 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
+     * @return the result of the evaluation or Double.NaN
+     * if the array is empty
+     * 
      */
     public double evaluate(
         final double[] values,
         final int start,
         final int length) {
 
-        return evaluate(values, start, length, percentile);
+        return evaluate(values, start, length, quantile);
     }
 
-    /**
+     /**
-     * Evaluates the double[] top the specified percentile.
+     * Returns an estimate of the <code>p</code>th percentile of the values
-     * This does not alter the interal percentile state of the
+     * in the <code>values</code> array, starting with the element in (0-based)
-     * statistic.
+     * position <code>begin</code> in the array and including <code>length</code>
+     * values.
+     * <p>
+     * Calls to this method do not modify the internal <code>quantile</code>
+     * state of this statistic.
+     * <p>
+      * See {@link Percentile} for a description of the percentile estimation algorithm used.
+     * 
      * @param values Is a double[] containing the values
-     * @param begin processing at this point in the array
+     * @param p Is the quantile to evaluate to.
-     * @param length the number of elements to include
+     * @param start  the first (0-based) element to include in the computation
-     * @param p Is the percentile to evaluate to.*
+     * @param length  the number of array elements to include
      * @return the result of the evaluation or Double.NaN
      * if the array is empty
      */
@@ -90,7 +121,7 @@ public class Percentile extends AbstractUnivariateStatistic implements Serializa
         test(values, begin, length);
 
         if ((p > 100) || (p <= 0)) {
-            throw new IllegalArgumentException("invalid percentile value");
+            throw new IllegalArgumentException("invalid quantile value");
         }
         double n = (double) length;
         if (n == 0) {
@@ -119,21 +150,23 @@ public class Percentile extends AbstractUnivariateStatistic implements Serializa
     }
 
     /**
-     * The default internal state of this percentile can be set.
+     * Returns the value of the quantile field (determines what percentile is computed when evaluate()
-     * This will return that value.
+     * is called with no quantile argument)
-     * @return percentile
+     * 
+     * @return quantile
      */
-    public double getPercentile() {
+    public double getQuantile() {
-        return percentile;
+        return quantile;
     }
 
     /**
-     * The default internal state of this percentile can be set.
+     * Sets the value of the quantile field (determines what percentile is computed when evaluate()
-     * This will setthat value.
+     * is called with no quantile argument)
-     * @param p a value between 0 <= p <= 100
+     * 
+     * @param p a value between 0 <= p <= 100 
      */
-    public void setPercentile(final double p) {
+    public void setQuantile(final double p) {
-        percentile = p;
+        quantile = p;
     }
 
 }