Java Doc for Percentile.java in  » Science » Apache-commons-math-1.1 » org » apache » commons » math » stat » descriptive » rank » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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 algorithm implemented here works as follows:

1. Let n be the length of the (sorted) array and 0 < p <= 100 be the desired percentile.
2. If n = 1 return the unique array element (regardless of the value of p); otherwise
3. Compute the estimated percentile position pos = p * (n + 1) / 100 and the difference, d between pos and floor(pos) (i.e. the fractional part of pos). If pos >= n return the largest element in the array; otherwise
4. Let lower be the element in position floor(pos) in the array and let upper be the next element in the array. Return lower + d * (upper - lower)

To compute percentiles, the data must be (totally) ordered. Input arrays are copied and then sorted using java.util.Arrays.sort(double[]) . The ordering used by Arrays.sort(double[]) is the one determined by java.lang.Double.compareTo(Double) . This ordering makes Double.NaN larger than any other value (including Double.POSITIVE_INFINITY). Therefore, for example, the median (50th percentile) of {0, 1, 2, 3, 4, Double.NaN} evaluates to 2.5.

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: 348519 $ $Date: 2005-11-23 12:12:18 -0700 (Wed, 23 Nov 2005) $

Calls to this method do not modify the internal quantile state of this statistic.

• Returns Double.NaN if values has length 0
• Returns (for any value of p) values[0] if values has length 1
• Throws IllegalArgumentException if values is null or p is not a valid quantile value (p must be greater than 0 and less than or equal to 100)

See Percentile for a description of the percentile estimation algorithm used.
Parameters:
  values - input array of values
Parameters:
  p - the percentile value to compute the percentile value or Double.NaN if the array is empty
throws:
  IllegalArgumentException - if values is null or p is invalid

• Returns Double.NaN if length = 0
• Returns (for any value of quantile) values[begin] if length = 1
• Throws IllegalArgumentException if values is null, or start or length is invalid

See Percentile for a description of the percentile estimation algorithm used.
Parameters:
  values - the input array
Parameters:
  start - index of the first array element to include
Parameters:
  length - the number of elements to include the percentile value
throws:
  IllegalArgumentException - if the parameters are not valid

Calls to this method do not modify the internal quantile state of this statistic.

• Returns Double.NaN if length = 0
• Returns (for any value of p) values[begin] if length = 1
• Throws IllegalArgumentException if values is null , begin or length is invalid, or p is not a valid quantile value (p must be greater than 0 and less than or equal to 100)

See Percentile for a description of the percentile estimation algorithm used.
Parameters:
  values - array of input values
Parameters:
  p - the percentile to compute
Parameters:
  begin - the first (0-based) element to include in the computation
Parameters:
  length - the number of array elements to include the percentile value
throws:
  IllegalArgumentException - if the parameters are not valid or theinput array is null