Class Percentile
- All Implemented Interfaces:
Serializable
,UnivariateStatistic
- Direct Known Subclasses:
Median
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 and0 invalid input: '<' p invalid input: '<'= 100
be the desired percentile. - If
n = 1
return the unique array element (regardless of the value ofp
); otherwise - Compute the estimated percentile position
pos = p * (n + 1) / 100
and the difference,d
betweenpos
andfloor(pos)
(i.e. the fractional part ofpos
). Ifpos >= n
return the largest element in the array; otherwise - Let
lower
be the element in positionfloor(pos)
in the array and letupper
be the next element in the array. Returnlower + d * (upper - lower)
To compute percentiles, the data must be at least partially ordered. Input
arrays are copied and recursively partitioned using an ordering definition.
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.
Since 2.2, Percentile implementation uses only selection instead of complete
sorting and caches selection algorithm state between calls to the various
evaluate
methods when several percentiles are to be computed on the same data.
This greatly improves efficiency, both for single percentile and multiple
percentiles computations. However, it also induces a need to be sure the data
at one call to evaluate
is the same as the data with the cached algorithm
state from the previous calls. Percentile does this by checking the array reference
itself and a checksum of its content by default. If the user already knows he calls
evaluate
on an immutable array, he can save the checking time by calling the
evaluate
methods that do not
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: 1006299 $ $Date: 2010-10-10 16:47:17 +0200 (dim. 10 oct. 2010) $
- See Also:
-
Constructor Summary
ConstructorsConstructorDescriptionConstructs 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 newPercentile
identical to theoriginal
-
Method Summary
Modifier and TypeMethodDescriptioncopy()
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 p) Returns the result of evaluating the statistic over the stored data.double
evaluate
(double[] values, double p) Returns an estimate of thep
th percentile of the values in thevalues
array.double
evaluate
(double[] values, int start, int length) Returns an estimate of thequantile
th percentile of the designated values in thevalues
array.double
evaluate
(double[] values, int begin, int length, double p) Returns an estimate of thep
th percentile of the values in thevalues
array, starting with the element in (0-based) positionbegin
in the array and includinglength
values.double
Returns the value of the quantile field (determines what percentile is computed when evaluate() is called with no quantile argument).void
setData
(double[] values) Set the data array.void
setData
(double[] values, int begin, int length) Set the data array.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.commons.math.stat.descriptive.AbstractUnivariateStatistic
evaluate, evaluate, getData, getDataRef, test, test
-
Constructor Details
-
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:
IllegalArgumentException
- if p is not greater than 0 and less than or equal to 100
-
Percentile
Copy constructor, creates a newPercentile
identical to theoriginal
- Parameters:
original
- thePercentile
instance to copy
-
-
Method Details
-
setData
public void setData(double[] values) Set the data array.The stored value is a copy of the parameter array, not the array itself
- Overrides:
setData
in classAbstractUnivariateStatistic
- Parameters:
values
- data array to store (may be null to remove stored data)- See Also:
-
setData
public void setData(double[] values, int begin, int length) Set the data array.- Overrides:
setData
in classAbstractUnivariateStatistic
- Parameters:
values
- data array to storebegin
- the index of the first element to includelength
- the number of elements to include- See Also:
-
evaluate
public double evaluate(double p) Returns the result of evaluating the statistic over the stored data.The stored array is the one which was set by previous calls to
- Parameters:
p
- the percentile value to compute- Returns:
- the value of the statistic applied to the stored data
-
evaluate
public double evaluate(double[] values, double p) Returns an estimate of thep
th percentile of the values in thevalues
array.Calls to this method do not modify the internal
quantile
state of this statistic.- Returns
Double.NaN
ifvalues
has length0
- Returns (for any value of
p
)values[0]
ifvalues
has length1
- Throws
IllegalArgumentException
ifvalues
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:
IllegalArgumentException
- ifvalues
is null or p is invalid
- Returns
-
evaluate
public double evaluate(double[] values, int start, int length) Returns an estimate of thequantile
th percentile of the designated values in thevalues
array. The quantile estimated is determined by thequantile
property.- Returns
Double.NaN
iflength = 0
- Returns (for any value of
quantile
)values[begin]
iflength = 1
- Throws
IllegalArgumentException
ifvalues
is null, orstart
orlength
is invalid
See
Percentile
for a description of the percentile estimation algorithm used.- Specified by:
evaluate
in interfaceUnivariateStatistic
- Specified by:
evaluate
in classAbstractUnivariateStatistic
- Parameters:
values
- the input arraystart
- index of the first array element to includelength
- the number of elements to include- Returns:
- the percentile value
- Throws:
IllegalArgumentException
- if the parameters are not valid
- Returns
-
evaluate
public double evaluate(double[] values, int begin, int length, double p) Returns an estimate of thep
th percentile of the values in thevalues
array, starting with the element in (0-based) positionbegin
in the array and includinglength
values.Calls to this method do not modify the internal
quantile
state of this statistic.- Returns
Double.NaN
iflength = 0
- Returns (for any value of
p
)values[begin]
iflength = 1
- Throws
IllegalArgumentException
ifvalues
is null ,begin
orlength
is invalid, orp
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 valuesbegin
- the first (0-based) element to include in the computationlength
- the number of array elements to includep
- the percentile to compute- Returns:
- the percentile value
- Throws:
IllegalArgumentException
- if the parameters are not valid or the input array is null
- Returns
-
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 invalid input: '<' p invalid input: '<'= 100- Throws:
IllegalArgumentException
- if p is not greater than 0 and less than or equal to 100
-
copy
Returns a copy of the statistic with the same internal state.- Specified by:
copy
in interfaceUnivariateStatistic
- Specified by:
copy
in classAbstractUnivariateStatistic
- Returns:
- a copy of the statistic
-
copy
Copies source to dest.Neither source nor dest can be null.
- Parameters:
source
- Percentile to copydest
- Percentile to copy to- Throws:
NullPointerException
- if either source or dest is null
-