org.apache.commons.math.stat.descriptive.rank
Class Percentile
java.lang.Object
org.apache.commons.math.stat.descriptive.AbstractUnivariateStatistic
org.apache.commons.math.stat.descriptive.rank.Percentile
- All Implemented Interfaces:
- java.io.Serializable, UnivariateStatistic
- Direct Known Subclasses:
- Median
- 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:
- Let
n
be the length of the (sorted) array and
0 < p <= 100
be the desired percentile.
- If
n = 1
return the unique array element (regardless of
the value of p
); otherwise
- 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
- 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.
- Version:
- $Revision: 1.1 $ $Date: 2004/10/08 05:08:17 $
- See Also:
- Serialized Form
Field Summary |
private double |
quantile
Determines what percentile is computed when evaluate() is activated
with no quantile argument |
(package private) static long |
serialVersionUID
Serializable version identifier |
Constructor Summary |
Percentile()
Constructs a Percentile with a default quantile
value of 50.0. |
Percentile(double p)
Constructs a Percentile with the specific quantile value. |
Method Summary |
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). |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
serialVersionUID
static final long serialVersionUID
- Serializable version identifier
- See Also:
- Constant Field Values
quantile
private double quantile
- Determines what percentile is computed when evaluate() is activated
with no quantile argument
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
evaluate
public double evaluate(double[] values,
double p)
- Returns an estimate of the
p
th 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 valuesp
- 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
quantile
th 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 arraystart
- index of the first array element to includelength
- the number of elements to include
- Returns:
- the percentile value
- Throws:
java.lang.IllegalArgumentException
- if the parameters are not valid- See Also:
UnivariateStatistic.evaluate(double[], int, int)
evaluate
public 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.
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 valuesp
- the percentile to computebegin
- the first (0-based) element to include in the computationlength
- 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