public class Percentile extends AbstractUnivariateStatistic implements Serializable
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:
n be the length of the (sorted) array and 0 < p <= 100 be
the desired percentile. n = 1 return the unique array element (regardless of the value of
p); otherwise pos = p * (n + 1) / 100 and the difference,
d between pos and floor(pos) (i.e. the fractional
part of pos).pos < 1 return the smallest element in the array.pos >= n return the largest element in the array.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 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 uses only selection instead of complete sorting and caches selection algorithm state between
calls to the various evaluate methods. This greatly improves efficiency, both for a single percentile and
multiple percentile computations. To maximize performance when multiple percentiles are computed based on the same
data, users should set the data array once using either one of the evaluate(double[], double) or
setData(double[]) methods and thereafter evaluate(double) with just the percentile provided.
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.
| 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 |
| 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 p)
Returns the result of evaluating the statistic over the stored data.
|
double |
evaluate(double[] values)
Returns an estimate of the
quantileth percentile of the values array. |
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).
|
int |
medianOf3(double[] work,
int begin,
int end)
Select a pivot index as the median of three
|
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).
|
evaluate, getData, getDataRef, test, test, test, testpublic Percentile()
public Percentile(double p)
p - the quantileMathIllegalArgumentException - if p is not greater than 0 and less
than or equal to 100public Percentile(Percentile original)
Percentile identical
to the originaloriginal - the Percentile instance to copyNullArgumentException - if original is nullpublic void setData(double[] values)
The stored value is a copy of the parameter array, not the array itself.
setData in class AbstractUnivariateStatisticvalues - data array to store (may be null to remove stored data)AbstractUnivariateStatistic.evaluate()public void setData(double[] values,
int begin,
int length)
setData in class AbstractUnivariateStatisticvalues - data array to storebegin - the index of the first element to includelength - the number of elements to includeAbstractUnivariateStatistic.evaluate()public double evaluate(double p)
The stored array is the one which was set by previous calls to setData(double[])
p - the percentile value to computeMathIllegalArgumentException - if p is not a valid quantile value
(p must be greater than 0 and less than or equal to 100)public double evaluate(double[] values)
quantileth percentile of the values array. The quantile
estimated is determined by
the quantile property.
Double.NaN if values has length 0p) values[0] if values has length
1IllegalArgumentException if values is null
See Percentile for a description of the percentile estimation algorithm used.
evaluate in interface UnivariateStatisticevaluate in interface MathArrays.Functionevaluate in class AbstractUnivariateStatisticvalues - input array of valuesIllegalArgumentException - if values is null
or p is invalidpublic double evaluate(double[] values,
double p)
pth percentile of the values
in the values array.
Calls to this method do not modify the internal quantile state of this statistic.
Double.NaN if values has length 0p) values[0] if values has length
1MathIllegalArgumentException 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.
values - input array of valuesp - the percentile value to computeMathIllegalArgumentException - if values is null
or p is invalidpublic double evaluate(double[] values,
int start,
int length)
quantileth percentile of the
designated values in the values array. The quantile
estimated is determined by the quantile property.
Double.NaN if length = 0quantile) values[begin] if length = 1 MathIllegalArgumentException if values is null, or start or
length is invalid
See Percentile for a description of the percentile estimation algorithm used.
evaluate in interface UnivariateStatisticevaluate in interface MathArrays.Functionevaluate in class AbstractUnivariateStatisticvalues - the input arraystart - index of the first array element to includelength - the number of elements to includeMathIllegalArgumentException - if the parameters are not validpublic double evaluate(double[] values,
int begin,
int length,
double p)
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.
Double.NaN if length = 0p) values[begin] if length = 1 MathIllegalArgumentException 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.
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 includeMathIllegalArgumentException - if the parameters are not valid or the
input array is nullpublic int medianOf3(double[] work,
int begin,
int end)
work - data arraybegin - index of the first element of the sliceend - index after the last element of the slicepublic double getQuantile()
public void setQuantile(double p)
p - a value between 0 < p <= 100MathIllegalArgumentException - if p is not greater than 0 and less
than or equal to 100public Percentile copy()
copy in interface UnivariateStatisticcopy in class AbstractUnivariateStatisticpublic static void copy(Percentile source, Percentile dest)
Neither source nor dest can be null.
source - Percentile to copydest - Percentile to copy toNullArgumentException - if either source or dest is nullCopyright © 2023 CNES. All rights reserved.