Percentile

java.lang.Object
- org.apache.openejb.math.stat.descriptive.AbstractUnivariateStatistic
- - org.apache.openejb.math.stat.descriptive.rank.Percentile

All Implemented Interfaces:

java.io.Serializable, UnivariateStatistic
```
public class Percentile
extends AbstractUnivariateStatistic
implements java.io.Serializable
```
Provides percentile computation.
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 Arrays.sort(double[]). The ordering used by Arrays.sort(double[]) is the one determined by 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.
See Also: Serialized Form










Constructor Summary

Constructors 

Constructor and Description


Percentile()
Constructs a Percentile with a default quantile
 value of 50.0.



Percentile(double p)
Constructs a Percentile with the specific quantile value.



Percentile(Percentile original)
Copy constructor, creates a new Percentile identical
 to the original










Method Summary

All Methods Static Methods Instance Methods Concrete Methods 

Modifier and Type
Method and Description


Percentile
copy()
Returns a copy of the statistic with the same internal state.



static void
copy(Percentile source,
    Percentile dest)
Copies source to dest.



double
evaluate(double[] values,
        double p)
Returns an estimate of the pth percentile of the values
 in the values array.



double
evaluate(double[] values,
        int start,
        int length)
Returns an estimate of the quantileth percentile of the
 designated values in the values array.



double
evaluate(double[] values,
        int begin,
        int length,
        double p)
Returns an estimate of the pth percentile of the values
 in the values array, starting with the element in (0-based)
 position begin in the array and including length
 values.



double
getQuantile()
Returns the value of the quantile field (determines what percentile is
 computed when evaluate() is called with no quantile argument).



void
setQuantile(double p)
Sets the value of the quantile field (determines what percentile is
 computed when evaluate() is called with no quantile argument).







Methods inherited from class org.apache.openejb.math.stat.descriptive.AbstractUnivariateStatistic
evaluate, test, test





Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait














Constructor Detail





Percentile
public Percentile()
Constructs a Percentile with a default quantile
 value of 50.0.







Percentile
public Percentile(double p)
Constructs a Percentile with the specific quantile value.

Parameters:
p - the quantile
Throws:
java.lang.IllegalArgumentException - if p is not greater than 0 and less
                                  than or equal to 100








Percentile
public Percentile(Percentile original)
Copy constructor, creates a new Percentile identical
 to the original

Parameters:
original - the Percentile instance to copy










Method Detail





evaluate
public double evaluate(double[] values,
                       double p)
Returns an estimate of the pth percentile of the values
 in the values array.
 
 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
p - the percentile value to compute
Returns:
the percentile value or Double.NaN if the array is empty
Throws:
java.lang.IllegalArgumentException - if values is null
                                  or p is invalid








evaluate
public double evaluate(double[] values,
                       int start,
                       int length)
Returns an estimate of the quantileth percentile of the
 designated values in the values array.  The quantile
 estimated is determined by the quantile property.
 
 

 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.

Specified by:
evaluate in interface UnivariateStatistic
Specified by:
evaluate in class AbstractUnivariateStatistic
Parameters:
values - the input array
start - index of the first array element to include
length - the number of elements to include
Returns:
the percentile value
Throws:
java.lang.IllegalArgumentException - if the parameters are not valid








evaluate
public double evaluate(double[] values,
                       int begin,
                       int length,
                       double p)
Returns an estimate of the pth percentile of the values
 in the values array, starting with the element in (0-based)
 position begin in the array and including length
 values.
 
 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
p - the percentile to compute
begin - the first (0-based) element to include in the computation
length - the number of array elements to include
Returns:
the percentile value
Throws:
java.lang.IllegalArgumentException - if the parameters are not valid or the
                                  input array is null








getQuantile
public double getQuantile()
Returns the value of the quantile field (determines what percentile is
 computed when evaluate() is called with no quantile argument).

Returns:
quantile








setQuantile
public void setQuantile(double p)
Sets the value of the quantile field (determines what percentile is
 computed when evaluate() is called with no quantile argument).

Parameters:
p - a value between 0 < p <= 100
Throws:
java.lang.IllegalArgumentException - if p is not greater than 0 and less
                                  than or equal to 100








copy
public Percentile copy()
Returns a copy of the statistic with the same internal state.

Specified by:
copy in interface UnivariateStatistic
Specified by:
copy in class AbstractUnivariateStatistic
Returns:
a copy of the statistic








copy
public static void copy(Percentile source,
                        Percentile dest)
Copies source to dest.
 Neither source nor dest can be null.

Parameters:
source - Percentile to copy
dest - Percentile to copy to
Throws:
java.lang.NullPointerException - if either source or dest is null

Modifier and Type	Method and Description
`Percentile`	`copy()` Returns a copy of the statistic with the same internal state.
`static void`	`copy(Percentile source, Percentile dest)` Copies source to dest.
`double`	`evaluate(double[] values, double p)` Returns an estimate of the `p`th percentile of the values in the `values` array.
`double`	`evaluate(double[] values, int start, int length)` Returns an estimate of the `quantile`th percentile of the designated values in the `values` array.
`double`	`evaluate(double[] values, int begin, int length, double p)` Returns an estimate of the `p`th percentile of the values in the `values` array, starting with the element in (0-based) position `begin` in the array and including `length` values.
`double`	`getQuantile()` Returns the value of the quantile field (determines what percentile is computed when evaluate() is called with no quantile argument).
`void`	`setQuantile(double p)` Sets the value of the quantile field (determines what percentile is computed when evaluate() is called with no quantile argument).

Class Percentile

Constructor Summary

Method Summary

Methods inherited from class org.apache.openejb.math.stat.descriptive.AbstractUnivariateStatistic

Methods inherited from class java.lang.Object

Constructor Detail

Percentile

Percentile

Percentile

Method Detail

evaluate

evaluate

evaluate

getQuantile

setQuantile

copy

copy