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 < 1 return the smallest element in the array.
Else if pos >= n return the largest element in the array.
Else 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 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 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.

Further, to include different estimation types such as R1, R2 as mentioned in Quantile page(wikipedia), a type specific NaN handling strategy is used to closely match with the typically observed results from popular tools like R(R1-R9), Excel(R7).

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.

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static enum	Percentile.EstimationType An enum for various estimation strategies of a percentile referred in wikipedia on quantile with the names of enum matching those of types mentioned in wikipedia.

Field Summary

Modifier and Type	Field and Description
private int[]	cachedPivots Cached pivots.
private final Percentile.EstimationType	estimationType Any of the `EstimationType`s such as `CM` can be used.
private final KthSelector	kthSelector Default KthSelector used with default pivoting strategy
private static final int	MAX_CACHED_LEVELS Maximum number of partitioning pivots cached (each level double the number of pivots).
private final NaNStrategy	nanStrategy NaN Handling of the input as defined by `NaNStrategy`
private static final int	PIVOTS_HEAP_LENGTH Maximum number of cached pivots in the pivots cached array
private double	quantile Determines what percentile is computed when evaluate() is activated with no quantile argument
private static final long	serialVersionUID Serializable version identifier

Constructor Summary

Access	Constructor and Description
public	Percentile() Constructs a Percentile with the following defaults.
public	Percentile(final double the quantile quantile) Constructs a Percentile with the specific quantile value and the following default method type: `EstimationType#LEGACY` default NaN strategy: `NaNStrategy#REMOVED` a Kth Selector : `KthSelector`
public	Percentile(final Percentile the `Percentile` instance to copy original) Copy constructor, creates a new `Percentile` identical to the `original`
protected	Percentile(final double the quantile to be computed quantile, final Percentile.EstimationType one of the percentile `estimation types` estimationType, final NaNStrategy one of `NaNStrategy` to handle with NaNs nanStrategy, final KthSelector a `KthSelector` to use for pivoting during search kthSelector) Constructs a Percentile with the specific quantile value, `EstimationType`, `NaNStrategy` and `KthSelector`.

Method Summary

Modifier and Type	Method and Description
public Percentile	copy() Implements abstract org.apache.commons.math3.stat.descriptive.AbstractUnivariateStatistic.copy. Implements org.apache.commons.math3.stat.descriptive.UnivariateStatistic.copy. Returns a copy of the statistic with the same internal state.
public static void	copy(final Percentile Percentile to copy source, final Percentile Percentile to copy to dest) Deprecated as of 3.4 this method does not work anymore, as it fails to copy internal states between instances configured with different `estimation type`, `NaN handling strategies` and `kthSelector`, it therefore always throw `MathUnsupportedOperationException` Copies source to dest.
private static double[]	Returns: copy of a slice of the original array copyOf(final double[] the input array values, final int start index of the array to include begin, final int number of elements to include from begin length) Make a copy of the array for the slice defined by array part from [begin, begin+length)
public double	Returns: the value of the statistic applied to the stored data evaluate(final double the percentile value to compute p) Returns the result of evaluating the statistic over the stored data.
public double	Returns: the percentile value or Double.NaN if the array is empty evaluate(final double[] input array of values values, final double the percentile value to compute p) Returns an estimate of the `p`th percentile of the values in the `values` array.
public double	Returns: the percentile value evaluate(final double[] the input array values, final int index of the first array element to include start, final int the number of elements to include length) Implements abstract org.apache.commons.math3.stat.descriptive.AbstractUnivariateStatistic.evaluate. Implements org.apache.commons.math3.stat.descriptive.UnivariateStatistic.evaluate. Returns an estimate of the `quantile`th percentile of the designated values in the `values` array.
public double	Returns: the percentile value evaluate(final double[] array of input values values, final int the first (0-based) element to include in the computation begin, final int the number of array elements to include length, final double the percentile to compute 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.
public Percentile.EstimationType	Returns: the `estimationType` set getEstimationType() Get the estimation `type` used for computation.
public KthSelector	Returns: the `kthSelector` set getKthSelector() Get the `kthSelector` used for computation.
public NaNStrategy	Returns: `NaN Handling` strategy set during construction getNaNStrategy() Get the `NaN Handling` strategy used for computation.
public PivotingStrategyInterface	Returns: the pivoting strategy set getPivotingStrategy() Get the `PivotingStrategyInterface` used in KthSelector for computation.
private int[]	Returns: cached pivots or a newly created one getPivots(final double[] array containing the input numbers values) Get pivots which is either cached or a newly created one
public double	Returns: quantile set while construction or `setQuantile(double)` getQuantile() Returns the value of the quantile field (determines what percentile is computed when evaluate() is called with no quantile argument).
protected double[]	Returns: work array sliced from values in the range [begin,begin+length) getWorkArray(final double[] the array of numbers values, final int index to start reading the array begin, final int the length of array to be read from the begin index length) Get the work array to operate.
pack-priv int	Returns: the index of the median element chosen between the first, the middle and the last element of the array slice medianOf3(final double[] data array work, final int index of the first element of the slice begin, final int index after the last element of the slice end) Deprecated Please refrain from using this method (as it wont take effect) and instead use `Percentile#withKthSelector(newKthSelector)` if required. Select a pivot index as the median of three Note With the effect of allowing `KthSelector` to be set on `Percentile` instances(thus indirectly `PivotingStrategy`) this method wont take effect any more and hence is unsupported.
private static double[]	Returns: the copy of the sliced array after removing the removedValue removeAndSlice(final double[] the input array values, final int start index of the array to include begin, final int number of elements to include from begin length, final double the value to be removed from the sliced array removedValue) Remove the occurrence of a given value in a copied slice of array defined by the array part from [begin, begin+length).
private static double[]	Returns: the copy of sliced array with replaced values replaceAndSlice(final double[] the input array values, final int start index of the array to include begin, final int number of elements to include from begin length, final double the value to be replaced with original, final double the value to be used for replacement replacement) Replace every occurrence of a given value with a replacement value in a copied slice of array defined by array part from [begin, begin+length).
public void	setData(final double[] data array to store (may be null to remove stored data) values) Overrides org.apache.commons.math3.stat.descriptive.AbstractUnivariateStatistic.setData. Set the data array.
public void	setData(final double[] data array to store values, final int the index of the first element to include begin, final int the number of elements to include length) Overrides org.apache.commons.math3.stat.descriptive.AbstractUnivariateStatistic.setData. Set the data array.
public void	setQuantile(final double a value between 0 < p <= 100 p) Sets the value of the quantile field (determines what percentile is computed when evaluate() is called with no quantile argument).
public Percentile	Returns: a new instance, with changed estimation type withEstimationType(final Percentile.EstimationType estimation type for the new instance newEstimationType) Build a new instance similar to the current one except for the `estimation type`.
public Percentile	Returns: a new instance, with changed KthSelector withKthSelector(final KthSelector KthSelector for the new instance newKthSelector) Build a new instance similar to the current one except for the `kthSelector` instance specifically set.
public Percentile	Returns: a new instance, with changed NaN handling strategy withNaNStrategy(final NaNStrategy NaN strategy for the new instance newNaNStrategy) Build a new instance similar to the current one except for the `NaN handling` strategy.

Inherited from org.apache.commons.math3.stat.descriptive.AbstractUnivariateStatistic:: evaluate evaluate getData getDataRef test test test test

Field Detail

cachedPivots	back to summary
private int[] cachedPivots Cached pivots.

estimationType	back to summary
private final Percentile.EstimationType estimationType Any of the `EstimationType`s such as `CM` can be used.

kthSelector	back to summary
private final KthSelector kthSelector Default KthSelector used with default pivoting strategy

MAX_CACHED_LEVELS	back to summary
private static final int MAX_CACHED_LEVELS Maximum number of partitioning pivots cached (each level double the number of pivots).

nanStrategy	back to summary
private final NaNStrategy nanStrategy NaN Handling of the input as defined by `NaNStrategy`

PIVOTS_HEAP_LENGTH	back to summary
private static final int PIVOTS_HEAP_LENGTH Maximum number of cached pivots in the pivots cached array

quantile	back to summary
private double quantile Determines what percentile is computed when evaluate() is activated with no quantile argument

serialVersionUID	back to summary
private static final long serialVersionUID Serializable version identifier

Constructor Detail

Percentile back to summary

Percentile	back to summary
public Percentile() Constructs a Percentile with the following defaults. default quantile: 50.0, can be reset with `setQuantile(double)` default estimation type: `EstimationType#LEGACY`, can be reset with `withEstimationType(EstimationType)` default NaN strategy: `NaNStrategy#REMOVED`, can be reset with `withNaNStrategy(NaNStrategy)` a KthSelector that makes use of `MedianOf3PivotingStrategy`, can be reset with `withKthSelector(KthSelector)`

public Percentile()

Constructs a Percentile with the following defaults.

default quantile: 50.0, can be reset with setQuantile(double)
default estimation type: EstimationType#LEGACY, can be reset with withEstimationType(EstimationType)
default NaN strategy: NaNStrategy#REMOVED, can be reset with withNaNStrategy(NaNStrategy)
a KthSelector that makes use of MedianOf3PivotingStrategy, can be reset with withKthSelector(KthSelector)

Percentile back to summary

Percentile	back to summary
public Percentile(final double quantile) throws MathIllegalArgumentException Constructs a Percentile with the specific quantile value and the following default method type: `EstimationType#LEGACY` default NaN strategy: `NaNStrategy#REMOVED` a Kth Selector : `KthSelector` Parameters quantile:double the quantile Exceptions MathIllegalArgumentException: if p is not greater than 0 and less than or equal to 100

public Percentile(final double quantile) throws MathIllegalArgumentException

Constructs a Percentile with the specific quantile value and the following

default method type: EstimationType#LEGACY
default NaN strategy: NaNStrategy#REMOVED
a Kth Selector : KthSelector

Parameters

quantile:double: the quantile

Exceptions

MathIllegalArgumentException:: if p is not greater than 0 and less than or equal to 100

Percentile back to summary

Percentile	back to summary
public Percentile(final Percentile original) throws NullArgumentException Copy constructor, creates a new `Percentile` identical to the `original` Parameters original:Percentile the `Percentile` instance to copy Exceptions NullArgumentException: if original is null

public Percentile(final Percentile original) throws NullArgumentException

Copy constructor, creates a new Percentile identical to the original

Parameters

original:Percentile: the Percentile instance to copy

Exceptions

NullArgumentException:: if original is null

Percentile back to summary

Percentile	back to summary
protected Percentile(final double quantile, final Percentile.EstimationType estimationType, final NaNStrategy nanStrategy, final KthSelector kthSelector) throws MathIllegalArgumentException Constructs a Percentile with the specific quantile value, `EstimationType`, `NaNStrategy` and `KthSelector`. Parameters quantile:double the quantile to be computed estimationType:Percentile.EstimationType one of the percentile `estimation types` nanStrategy:NaNStrategy one of `NaNStrategy` to handle with NaNs kthSelector:KthSelector a `KthSelector` to use for pivoting during search Exceptions MathIllegalArgumentException: if p is not within (0,100] NullArgumentException: if type or NaNStrategy passed is null

protected Percentile(final double quantile, final Percentile.EstimationType estimationType, final NaNStrategy nanStrategy, final KthSelector kthSelector) throws MathIllegalArgumentException

Constructs a Percentile with the specific quantile value, EstimationType, NaNStrategy and KthSelector.

Parameters

quantile:double: the quantile to be computed
estimationType:Percentile.EstimationType: one of the percentile estimation types
nanStrategy:NaNStrategy: one of NaNStrategy to handle with NaNs
kthSelector:KthSelector: a KthSelector to use for pivoting during search

Exceptions

MathIllegalArgumentException:: if p is not within (0,100]
NullArgumentException:: if type or NaNStrategy passed is null

Method Detail

copy	back to summary
public Percentile copy() Implements abstract org.apache.commons.math3.stat.descriptive.AbstractUnivariateStatistic.copy. Implements org.apache.commons.math3.stat.descriptive.UnivariateStatistic.copy. Doc from org.apache.commons.math3.stat.descriptive.AbstractUnivariateStatistic.copy. Returns a copy of the statistic with the same internal state. Returns:Percentile Doc from org.apache.commons.math3.stat.descriptive.UnivariateStatistic.copy. a copy of the statistic Annotations @Override

copy

back to summary

public Percentile copy()

Implements abstract org.apache.commons.math3.stat.descriptive.AbstractUnivariateStatistic.copy.

Implements org.apache.commons.math3.stat.descriptive.UnivariateStatistic.copy.

Doc from org.apache.commons.math3.stat.descriptive.AbstractUnivariateStatistic.copy.

Returns a copy of the statistic with the same internal state.

Returns:Percentile

Doc from org.apache.commons.math3.stat.descriptive.UnivariateStatistic.copy.

a copy of the statistic

Annotations

@Override

copy back to summary

copy	back to summary
public static void copy(final Percentile source, final Percentile dest) throws MathUnsupportedOperationException Deprecated as of 3.4 this method does not work anymore, as it fails to copy internal states between instances configured with different `estimation type`, `NaN handling strategies` and `kthSelector`, it therefore always throw `MathUnsupportedOperationException` Copies source to dest. Parameters source:Percentile Percentile to copy dest:Percentile Percentile to copy to Annotations @Deprecated Exceptions MathUnsupportedOperationException: always thrown since 3.4

public static void copy(final Percentile source, final Percentile dest) throws MathUnsupportedOperationException

Deprecated

as of 3.4 this method does not work anymore, as it fails to copy internal states between instances configured with different estimation type, NaN handling strategies and kthSelector, it therefore always throw MathUnsupportedOperationException

Copies source to dest.

Parameters

source:Percentile: Percentile to copy
dest:Percentile: Percentile to copy to

Annotations

@Deprecated

Exceptions

MathUnsupportedOperationException:: always thrown since 3.4

copyOf	back to summary
private static double[] copyOf(final double[] values, final int begin, final int length) Make a copy of the array for the slice defined by array part from [begin, begin+length) Parameters values:double[] the input array begin:int start index of the array to include length:int number of elements to include from begin Returns:double[] copy of a slice of the original array

copyOf

back to summary

private static double[] copyOf(final double[] values, final int begin, final int length)

Make a copy of the array for the slice defined by array part from [begin, begin+length)

Parameters

values:double[]: the input array
begin:int: start index of the array to include
length:int: number of elements to include from begin

Returns:double[]

copy of a slice of the original array

evaluate back to summary

evaluate	back to summary
public double evaluate(final double p) throws MathIllegalArgumentException Returns the result of evaluating the statistic over the stored data. The stored array is the one which was set by previous calls to `setData(double[])` Parameters p:double the percentile value to compute Returns:double the value of the statistic applied to the stored data Exceptions MathIllegalArgumentException: if p is not a valid quantile value (p must be greater than 0 and less than or equal to 100)

public double evaluate(final double p) throws MathIllegalArgumentException

Returns the result of evaluating the statistic over the stored data.

The stored array is the one which was set by previous calls to setData(double[])

Parameters

p:double: the percentile value to compute

Returns:double

the value of the statistic applied to the stored data

Exceptions

MathIllegalArgumentException:: if p is not a valid quantile value (p must be greater than 0 and less than or equal to 100)

evaluate back to summary

evaluate	back to summary
public double evaluate(final double[] values, final double p) throws MathIllegalArgumentException 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 `MathIllegalArgumentException` 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:double[] input array of values p:double the percentile value to compute Returns:double the percentile value or Double.NaN if the array is empty Exceptions MathIllegalArgumentException: if `values` is null or p is invalid

public double evaluate(final double[] values, final double p) throws MathIllegalArgumentException

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 MathIllegalArgumentException 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:double[]: input array of values
p:double: the percentile value to compute

Returns:double

the percentile value or Double.NaN if the array is empty

Exceptions

MathIllegalArgumentException:: if values is null or p is invalid

evaluate back to summary

evaluate	back to summary
public double evaluate(final double[] values, final int start, final int length) throws MathIllegalArgumentException Implements abstract org.apache.commons.math3.stat.descriptive.AbstractUnivariateStatistic.evaluate. Implements org.apache.commons.math3.stat.descriptive.UnivariateStatistic.evaluate. 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 `MathIllegalArgumentException` if `values` is null, or `start` or `length` is invalid See `Percentile` for a description of the percentile estimation algorithm used. Parameters values:double[] the input array start:int index of the first array element to include length:int the number of elements to include Returns:double the percentile value Annotations @Override Exceptions MathIllegalArgumentException: if the parameters are not valid

public double evaluate(final double[] values, final int start, final int length) throws MathIllegalArgumentException

Implements abstract org.apache.commons.math3.stat.descriptive.AbstractUnivariateStatistic.evaluate.

Implements org.apache.commons.math3.stat.descriptive.UnivariateStatistic.evaluate.

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 MathIllegalArgumentException if values is null, or start or length is invalid

See Percentile for a description of the percentile estimation algorithm used.

Parameters

values:double[]: the input array
start:int: index of the first array element to include
length:int: the number of elements to include

Returns:double

the percentile value

Annotations

@Override

Exceptions

MathIllegalArgumentException:: if the parameters are not valid

evaluate back to summary

evaluate	back to summary
public double evaluate(final double[] values, final int begin, final int length, final double p) throws MathIllegalArgumentException 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 `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. Parameters values:double[] array of input values begin:int the first (0-based) element to include in the computation length:int the number of array elements to include p:double the percentile to compute Returns:double the percentile value Exceptions MathIllegalArgumentException: if the parameters are not valid or the input array is null

public double evaluate(final double[] values, final int begin, final int length, final double p) throws MathIllegalArgumentException

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 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.

Parameters

values:double[]: array of input values
begin:int: the first (0-based) element to include in the computation
length:int: the number of array elements to include
p:double: the percentile to compute

Returns:double

the percentile value

Exceptions

MathIllegalArgumentException:: if the parameters are not valid or the input array is null

getEstimationType back to summary

getEstimationType	back to summary
public Percentile.EstimationType getEstimationType() Get the estimation `type` used for computation. Returns:Percentile.EstimationType the `estimationType` set

public Percentile.EstimationType getEstimationType()

Get the estimation type used for computation.

Returns:Percentile.EstimationType: the estimationType set

getKthSelector back to summary

getKthSelector	back to summary
public KthSelector getKthSelector() Get the `kthSelector` used for computation. Returns:KthSelector the `kthSelector` set

public KthSelector getKthSelector()

Get the kthSelector used for computation.

Returns:KthSelector: the kthSelector set

getNaNStrategy back to summary

getNaNStrategy	back to summary
public NaNStrategy getNaNStrategy() Get the `NaN Handling` strategy used for computation. Returns:NaNStrategy `NaN Handling` strategy set during construction

public NaNStrategy getNaNStrategy()

Get the NaN Handling strategy used for computation.

Returns:NaNStrategy: NaN Handling strategy set during construction

getPivotingStrategy back to summary

getPivotingStrategy	back to summary
public PivotingStrategyInterface getPivotingStrategy() Get the `PivotingStrategyInterface` used in KthSelector for computation. Returns:PivotingStrategyInterface the pivoting strategy set

public PivotingStrategyInterface getPivotingStrategy()

Get the PivotingStrategyInterface used in KthSelector for computation.

Returns:PivotingStrategyInterface: the pivoting strategy set

getPivots	back to summary
private int[] getPivots(final double[] values) Get pivots which is either cached or a newly created one Parameters values:double[] array containing the input numbers Returns:int[] cached pivots or a newly created one

getPivots

back to summary

private int[] getPivots(final double[] values)

Get pivots which is either cached or a newly created one

Parameters

values:double[]: array containing the input numbers

Returns:int[]

cached pivots or a newly created one

getQuantile back to summary

getQuantile	back to summary
public double getQuantile() Returns the value of the quantile field (determines what percentile is computed when evaluate() is called with no quantile argument). Returns:double quantile set while construction or `setQuantile(double)`

public double getQuantile()

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

Returns:double: quantile set while construction or setQuantile(double)

getWorkArray back to summary

getWorkArray	back to summary
protected double[] getWorkArray(final double[] values, final int begin, final int length) Get the work array to operate. Makes use of prior `storedData` if it exists or else do a check on NaNs and copy a subset of the array defined by begin and length parameters. The set `nanStrategy` will be used to either retain/remove/replace any NaNs present before returning the resultant array. Parameters values:double[] the array of numbers begin:int index to start reading the array length:int the length of array to be read from the begin index Returns:double[] work array sliced from values in the range [begin,begin+length) Exceptions MathIllegalArgumentException: if values or indices are invalid

protected double[] getWorkArray(final double[] values, final int begin, final int length)

Get the work array to operate. Makes use of prior storedData if it exists or else do a check on NaNs and copy a subset of the array defined by begin and length parameters. The set nanStrategy will be used to either retain/remove/replace any NaNs present before returning the resultant array.

Parameters

values:double[]: the array of numbers
begin:int: index to start reading the array
length:int: the length of array to be read from the begin index

Returns:double[]

work array sliced from values in the range [begin,begin+length)

Exceptions

MathIllegalArgumentException:: if values or indices are invalid

medianOf3 back to summary

medianOf3	back to summary
pack-priv int medianOf3(final double[] work, final int begin, final int end) Deprecated Please refrain from using this method (as it wont take effect) and instead use `Percentile#withKthSelector(newKthSelector)` if required. Select a pivot index as the median of three Note With the effect of allowing `KthSelector` to be set on `Percentile` instances(thus indirectly `PivotingStrategy`) this method wont take effect any more and hence is unsupported. Parameters work:double[] data array begin:int index of the first element of the slice end:int index after the last element of the slice Returns:int the index of the median element chosen between the first, the middle and the last element of the array slice Annotations @Deprecated

pack-priv int medianOf3(final double[] work, final int begin, final int end)

Deprecated

Please refrain from using this method (as it wont take effect) and instead use Percentile#withKthSelector(newKthSelector) if required.

Select a pivot index as the median of three

Note

With the effect of allowing KthSelector to be set on Percentile instances(thus indirectly PivotingStrategy) this method wont take effect any more and hence is unsupported.

Parameters

work:double[]: data array
begin:int: index of the first element of the slice
end:int: index after the last element of the slice

Returns:int

the index of the median element chosen between the first, the middle and the last element of the array slice

Annotations

@Deprecated

removeAndSlice	back to summary
private static double[] removeAndSlice(final double[] values, final int begin, final int length, final double removedValue) Remove the occurrence of a given value in a copied slice of array defined by the array part from [begin, begin+length). Parameters values:double[] the input array begin:int start index of the array to include length:int number of elements to include from begin removedValue:double the value to be removed from the sliced array Returns:double[] the copy of the sliced array after removing the removedValue

removeAndSlice

back to summary

private static double[] removeAndSlice(final double[] values, final int begin, final int length, final double removedValue)

Remove the occurrence of a given value in a copied slice of array defined by the array part from [begin, begin+length).

Parameters

values:double[]: the input array
begin:int: start index of the array to include
length:int: number of elements to include from begin
removedValue:double: the value to be removed from the sliced array

Returns:double[]

the copy of the sliced array after removing the removedValue

replaceAndSlice	back to summary
private static double[] replaceAndSlice(final double[] values, final int begin, final int length, final double original, final double replacement) Replace every occurrence of a given value with a replacement value in a copied slice of array defined by array part from [begin, begin+length). Parameters values:double[] the input array begin:int start index of the array to include length:int number of elements to include from begin original:double the value to be replaced with replacement:double the value to be used for replacement Returns:double[] the copy of sliced array with replaced values

replaceAndSlice

back to summary

private static double[] replaceAndSlice(final double[] values, final int begin, final int length, final double original, final double replacement)

Replace every occurrence of a given value with a replacement value in a copied slice of array defined by array part from [begin, begin+length).

Parameters

values:double[]: the input array
begin:int: start index of the array to include
length:int: number of elements to include from begin
original:double: the value to be replaced with
replacement:double: the value to be used for replacement

Returns:double[]

the copy of sliced array with replaced values

setData	back to summary
public void setData(final double[] values) Overrides org.apache.commons.math3.stat.descriptive.AbstractUnivariateStatistic.setData. Doc from org.apache.commons.math3.stat.descriptive.AbstractUnivariateStatistic.setData. Set the data array. The stored value is a copy of the parameter array, not the array itself. Parameters values:double[] data array to store (may be null to remove stored data) Annotations @Override

setData

back to summary

public void setData(final double[] values)

Overrides org.apache.commons.math3.stat.descriptive.AbstractUnivariateStatistic.setData.

Doc from org.apache.commons.math3.stat.descriptive.AbstractUnivariateStatistic.setData.

Set the data array.

The stored value is a copy of the parameter array, not the array itself.

Parameters

values:double[]: data array to store (may be null to remove stored data)

Annotations

@Override

setData	back to summary
public void setData(final double[] values, final int begin, final int length) throws MathIllegalArgumentException Overrides org.apache.commons.math3.stat.descriptive.AbstractUnivariateStatistic.setData. Doc from org.apache.commons.math3.stat.descriptive.AbstractUnivariateStatistic.setData. Set the data array. The input array is copied, not referenced. Parameters values:double[] data array to store begin:int the index of the first element to include length:int the number of elements to include Annotations @Override Exceptions MathIllegalArgumentException: if values is null or the indices are not valid

setData

back to summary

public void setData(final double[] values, final int begin, final int length) throws MathIllegalArgumentException

Overrides org.apache.commons.math3.stat.descriptive.AbstractUnivariateStatistic.setData.

Doc from org.apache.commons.math3.stat.descriptive.AbstractUnivariateStatistic.setData.

Set the data array. The input array is copied, not referenced.

Parameters

values:double[]: data array to store
begin:int: the index of the first element to include
length:int: the number of elements to include

Annotations

@Override

Exceptions

MathIllegalArgumentException:: if values is null or the indices are not valid

setQuantile	back to summary
public void setQuantile(final double p) throws MathIllegalArgumentException Sets the value of the quantile field (determines what percentile is computed when evaluate() is called with no quantile argument). Parameters p:double a value between 0 < p <= 100 Exceptions MathIllegalArgumentException: if p is not greater than 0 and less than or equal to 100

setQuantile

back to summary

public void setQuantile(final double p) throws MathIllegalArgumentException

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

Parameters

p:double: a value between 0 < p <= 100

Exceptions

MathIllegalArgumentException:: if p is not greater than 0 and less than or equal to 100

withEstimationType back to summary

withEstimationType	back to summary
public Percentile withEstimationType(final Percentile.EstimationType newEstimationType) Build a new instance similar to the current one except for the `estimation type`. This method is intended to be used as part of a fluent-type builder pattern. Building finely tune instances should be done as follows: Percentile customized = new Percentile(quantile). withEstimationType(estimationType). withNaNStrategy(nanStrategy). withKthSelector(kthSelector); If any of the `withXxx` method is omitted, the default value for the corresponding customization parameter will be used. Parameters newEstimationType:Percentile.EstimationType estimation type for the new instance Returns:Percentile a new instance, with changed estimation type Exceptions NullArgumentException: when newEstimationType is null

public Percentile withEstimationType(final Percentile.EstimationType newEstimationType)

Build a new instance similar to the current one except for the estimation type.

This method is intended to be used as part of a fluent-type builder pattern. Building finely tune instances should be done as follows:

  Percentile customized = new Percentile(quantile).
                          withEstimationType(estimationType).
                          withNaNStrategy(nanStrategy).
                          withKthSelector(kthSelector);

If any of the withXxx method is omitted, the default value for the corresponding customization parameter will be used.

Parameters

newEstimationType:Percentile.EstimationType: estimation type for the new instance

Returns:Percentile

a new instance, with changed estimation type

Exceptions

NullArgumentException:: when newEstimationType is null

withKthSelector back to summary

withKthSelector	back to summary
public Percentile withKthSelector(final KthSelector newKthSelector) Build a new instance similar to the current one except for the `kthSelector` instance specifically set. This method is intended to be used as part of a fluent-type builder pattern. Building finely tune instances should be done as follows: Percentile customized = new Percentile(quantile). withEstimationType(estimationType). withNaNStrategy(nanStrategy). withKthSelector(newKthSelector); If any of the `withXxx` method is omitted, the default value for the corresponding customization parameter will be used. Parameters newKthSelector:KthSelector KthSelector for the new instance Returns:Percentile a new instance, with changed KthSelector Exceptions NullArgumentException: when newKthSelector is null

public Percentile withKthSelector(final KthSelector newKthSelector)

Build a new instance similar to the current one except for the kthSelector instance specifically set.

This method is intended to be used as part of a fluent-type builder pattern. Building finely tune instances should be done as follows:

  Percentile customized = new Percentile(quantile).
                          withEstimationType(estimationType).
                          withNaNStrategy(nanStrategy).
                          withKthSelector(newKthSelector);

If any of the withXxx method is omitted, the default value for the corresponding customization parameter will be used.

Parameters

newKthSelector:KthSelector: KthSelector for the new instance

Returns:Percentile

a new instance, with changed KthSelector

Exceptions

NullArgumentException:: when newKthSelector is null

withNaNStrategy back to summary

withNaNStrategy	back to summary
public Percentile withNaNStrategy(final NaNStrategy newNaNStrategy) Build a new instance similar to the current one except for the `NaN handling` strategy. This method is intended to be used as part of a fluent-type builder pattern. Building finely tune instances should be done as follows: Percentile customized = new Percentile(quantile). withEstimationType(estimationType). withNaNStrategy(nanStrategy). withKthSelector(kthSelector); If any of the `withXxx` method is omitted, the default value for the corresponding customization parameter will be used. Parameters newNaNStrategy:NaNStrategy NaN strategy for the new instance Returns:Percentile a new instance, with changed NaN handling strategy Exceptions NullArgumentException: when newNaNStrategy is null

public Percentile withNaNStrategy(final NaNStrategy newNaNStrategy)

Build a new instance similar to the current one except for the NaN handling strategy.

This method is intended to be used as part of a fluent-type builder pattern. Building finely tune instances should be done as follows:

  Percentile customized = new Percentile(quantile).
                          withEstimationType(estimationType).
                          withNaNStrategy(nanStrategy).
                          withKthSelector(kthSelector);

If any of the withXxx method is omitted, the default value for the corresponding customization parameter will be used.

Parameters

newNaNStrategy:NaNStrategy: NaN strategy for the new instance

Returns:Percentile

a new instance, with changed NaN handling strategy

Exceptions

NullArgumentException:: when newNaNStrategy is null

org.apache.commons.math3.stat.descriptive.rank back to summary

public sealed Enum Percentile.EstimationType

Class Inheritance

extends Enum<Percentile.EstimationType>

java.lang.Object
java.lang.Enum
org.apache.commons.math3.stat.descriptive.rank.Percentile.EstimationType

An enum for various estimation strategies of a percentile referred in wikipedia on quantile with the names of enum matching those of types mentioned in wikipedia.

Each enum corresponding to the specific type of estimation in wikipedia implements the respective formulae that specializes in the below aspects

An index method to calculate approximate index of the estimate
An estimate method to estimate a value found at the earlier computed index
A minLimit on the quantile for which first element of sorted input is returned as an estimate
A maxLimit on the quantile for which last element of sorted input is returned as an estimate

Users can now create Percentile by explicitly passing this enum; such as by invoking Percentile#withEstimationType(EstimationType)

References:

Field Summary

Modifier and Type	Field and Description
public static final Percentile.EstimationType	LEGACY This is the default type used in the `Percentile`.This method has the following formulae for index and estimates \( \begin{align} &index = (N+1)p\ \\ &estimate = x_{\lceil h\,-\,1/2 \rceil} \\ &minLimit = 0 \\ &maxLimit = 1 \\ \end{align}\)
private final String	name Hides java.lang.Enum.name. Simple name such as R-1, R-2 corresponding to those in wikipedia.
public static final Percentile.EstimationType	R_1 The method R_1 has the following formulae for index and estimates \( \begin{align} &index= Np + 1/2\, \\ &estimate= x_{\lceil h\,-\,1/2 \rceil} \\ &minLimit = 0 \\ \end{align}\)
public static final Percentile.EstimationType	R_2 The method R_2 has the following formulae for index and estimates \( \begin{align} &index= Np + 1/2\, \\ &estimate=\frac{x_{\lceil h\,-\,1/2 \rceil} + x_{\lfloor h\,+\,1/2 \rfloor}}{2} \\ &minLimit = 0 \\ &maxLimit = 1 \\ \end{align}\)
public static final Percentile.EstimationType	R_3 The method R_3 has the following formulae for index and estimates \( \begin{align} &index= Np \\ &estimate= x_{\lfloor h \rceil}\, \\ &minLimit = 0.5/N \\ \end{align}\)
public static final Percentile.EstimationType	R_4 The method R_4 has the following formulae for index and estimates \( \begin{align} &index= Np\, \\ &estimate= x_{\lfloor h \rfloor} + (h - \lfloor h \rfloor) (x_{\lfloor h \rfloor + 1} - x_{\lfloor h \rfloor}) \\ &minLimit = 1/N \\ &maxLimit = 1 \\ \end{align}\)
public static final Percentile.EstimationType	R_5 The method R_5 has the following formulae for index and estimates \( \begin{align} &index= Np + 1/2\\ &estimate= x_{\lfloor h \rfloor} + (h - \lfloor h \rfloor) (x_{\lfloor h \rfloor + 1} - x_{\lfloor h \rfloor}) \\ &minLimit = 0.5/N \\ &maxLimit = (N-0.5)/N \end{align}\)
public static final Percentile.EstimationType	R_6 The method R_6 has the following formulae for index and estimates \( \begin{align} &index= (N + 1)p \\ &estimate= x_{\lfloor h \rfloor} + (h - \lfloor h \rfloor) (x_{\lfloor h \rfloor + 1} - x_{\lfloor h \rfloor}) \\ &minLimit = 1/(N+1) \\ &maxLimit = N/(N+1) \\ \end{align}\) Note This method computes the index in a manner very close to the default Commons Math Percentile existing implementation.
public static final Percentile.EstimationType	R_7 The method R_7 implements Microsoft Excel style computation has the following formulae for index and estimates.
public static final Percentile.EstimationType	R_8 The method R_8 has the following formulae for index and estimates \( \begin{align} &index = (N + 1/3)p + 1/3 \\ &estimate = x_{\lfloor h \rfloor} + (h - \lfloor h \rfloor) (x_{\lfloor h \rfloor + 1} - x_{\lfloor h \rfloor}) \\ &minLimit = (2/3)/(N+1/3) \\ &maxLimit = (N-1/3)/(N+1/3) \\ \end{align}\) As per Ref [2,3] this approach is most recommended as it provides an approximate median-unbiased estimate regardless of distribution.
public static final Percentile.EstimationType	R_9 The method R_9 has the following formulae for index and estimates \( \begin{align} &index = (N + 1/4)p + 3/8\\ &estimate = x_{\lfloor h \rfloor} + (h - \lfloor h \rfloor) (x_{\lfloor h \rfloor + 1} - x_{\lfloor h \rfloor}) \\ &minLimit = (5/8)/(N+1/4) \\ &maxLimit = (N-3/8)/(N+1/4) \\ \end{align}\)

Constructor Summary

Access	Constructor and Description
private	EstimationType(final String name of estimation type as per wikipedia type) Constructor

Method Summary

Modifier and Type	Method and Description
protected double	Returns: estimated percentile estimate(final double[] array of numbers to be used for finding the percentile work, final int[] an earlier populated cache if exists; will be used pivotsHeap, final double indicated positional index prior computed from calling `index(double, int)` pos, final int size of array considered length, final KthSelector a `KthSelector` used for pivoting during search selector) Estimation based on K^th selection.
protected double	Returns: estimated percentile evaluate(final double[] array of numbers to be used for finding the percentile work, final int[] a prior cached heap which can speed up estimation pivotsHeap, final double the p^th quantile to be computed p, final KthSelector a `KthSelector` used for pivoting during search selector) Evaluate method to compute the percentile for a given bounded array using earlier computed pivots heap.
public double	Returns: estimated percentile evaluate(final double[] array of numbers to be used for finding the percentile work, final double the p^th quantile to be computed p, final KthSelector a `KthSelector` used for pivoting during search selector) Evaluate method to compute the percentile for a given bounded array.
pack-priv String	Returns: the name getName() Gets the name of the enum
protected abstract double	Returns: a computed real valued index as explained in the wikipedia index(final double the p^th quantile p, final int the total number of array elements in the work array length) Finds the index of array that can be used as starting index to `estimate` percentile.
public static Percentile.EstimationType	valueOf(String name)
public static Percentile.EstimationType[]	values()

Inherited from java.lang.Enum:: clone compareTo describeConstable equals finalize getDeclaringClass hashCode name ordinal toString valueOf

Field Detail

LEGACY	back to summary
public static final Percentile.EstimationType LEGACY This is the default type used in the `Percentile`.This method has the following formulae for index and estimates \( \begin{align} &index = (N+1)p\ \\ &estimate = x_{\lceil h\,-\,1/2 \rceil} \\ &minLimit = 0 \\ &maxLimit = 1 \\ \end{align}\)

name	back to summary
private final String name Hides java.lang.Enum.name. Simple name such as R-1, R-2 corresponding to those in wikipedia.

name

back to summary

private final String name

Hides java.lang.Enum.name.

Simple name such as R-1, R-2 corresponding to those in wikipedia.

R_1	back to summary
public static final Percentile.EstimationType R_1 The method R_1 has the following formulae for index and estimates \( \begin{align} &index= Np + 1/2\, \\ &estimate= x_{\lceil h\,-\,1/2 \rceil} \\ &minLimit = 0 \\ \end{align}\)

R_2	back to summary
public static final Percentile.EstimationType R_2 The method R_2 has the following formulae for index and estimates \( \begin{align} &index= Np + 1/2\, \\ &estimate=\frac{x_{\lceil h\,-\,1/2 \rceil} + x_{\lfloor h\,+\,1/2 \rfloor}}{2} \\ &minLimit = 0 \\ &maxLimit = 1 \\ \end{align}\)

R_3	back to summary
public static final Percentile.EstimationType R_3 The method R_3 has the following formulae for index and estimates \( \begin{align} &index= Np \\ &estimate= x_{\lfloor h \rceil}\, \\ &minLimit = 0.5/N \\ \end{align}\)

R_4	back to summary
public static final Percentile.EstimationType R_4 The method R_4 has the following formulae for index and estimates \( \begin{align} &index= Np\, \\ &estimate= x_{\lfloor h \rfloor} + (h - \lfloor h \rfloor) (x_{\lfloor h \rfloor + 1} - x_{\lfloor h \rfloor}) \\ &minLimit = 1/N \\ &maxLimit = 1 \\ \end{align}\)

R_5	back to summary
public static final Percentile.EstimationType R_5 The method R_5 has the following formulae for index and estimates \( \begin{align} &index= Np + 1/2\\ &estimate= x_{\lfloor h \rfloor} + (h - \lfloor h \rfloor) (x_{\lfloor h \rfloor + 1} - x_{\lfloor h \rfloor}) \\ &minLimit = 0.5/N \\ &maxLimit = (N-0.5)/N \end{align}\)

R_6	back to summary
public static final Percentile.EstimationType R_6 The method R_6 has the following formulae for index and estimates \( \begin{align} &index= (N + 1)p \\ &estimate= x_{\lfloor h \rfloor} + (h - \lfloor h \rfloor) (x_{\lfloor h \rfloor + 1} - x_{\lfloor h \rfloor}) \\ &minLimit = 1/(N+1) \\ &maxLimit = N/(N+1) \\ \end{align}\) Note This method computes the index in a manner very close to the default Commons Math Percentile existing implementation. However the difference to be noted is in picking up the limits with which first element (p<1(N+1)) and last elements (p>N/(N+1))are done. While in default case; these are done with p=0 and p=1 respectively.

R_6

back to summary

public static final Percentile.EstimationType R_6

The method R_6 has the following formulae for index and estimates
\( \begin{align} &index= (N + 1)p \\ &estimate= x_{\lfloor h \rfloor} + (h - \lfloor h \rfloor) (x_{\lfloor h \rfloor + 1} - x_{\lfloor h \rfloor}) \\ &minLimit = 1/(N+1) \\ &maxLimit = N/(N+1) \\ \end{align}\)

Note

This method computes the index in a manner very close to the default Commons Math Percentile existing implementation. However the difference to be noted is in picking up the limits with which first element (p<1(N+1)) and last elements (p>N/(N+1))are done. While in default case; these are done with p=0 and p=1 respectively.

R_7	back to summary
public static final Percentile.EstimationType R_7 The method R_7 implements Microsoft Excel style computation has the following formulae for index and estimates. \( \begin{align} &index = (N-1)p + 1 \\ &estimate = x_{\lfloor h \rfloor} + (h - \lfloor h \rfloor) (x_{\lfloor h \rfloor + 1} - x_{\lfloor h \rfloor}) \\ &minLimit = 0 \\ &maxLimit = 1 \\ \end{align}\)

R_8

back to summary

public static final Percentile.EstimationType R_8

The method R_8 has the following formulae for index and estimates
\( \begin{align} &index = (N + 1/3)p + 1/3 \\ &estimate = x_{\lfloor h \rfloor} + (h - \lfloor h \rfloor) (x_{\lfloor h \rfloor + 1} - x_{\lfloor h \rfloor}) \\ &minLimit = (2/3)/(N+1/3) \\ &maxLimit = (N-1/3)/(N+1/3) \\ \end{align}\)

As per Ref [2,3] this approach is most recommended as it provides an approximate median-unbiased estimate regardless of distribution.

R_9	back to summary
public static final Percentile.EstimationType R_9 The method R_9 has the following formulae for index and estimates \( \begin{align} &index = (N + 1/4)p + 3/8\\ &estimate = x_{\lfloor h \rfloor} + (h - \lfloor h \rfloor) (x_{\lfloor h \rfloor + 1} - x_{\lfloor h \rfloor}) \\ &minLimit = (5/8)/(N+1/4) \\ &maxLimit = (N-3/8)/(N+1/4) \\ \end{align}\)

Constructor Detail

EstimationType

back to summary

private EstimationType(final String type)

Constructor

Parameters

type:String: name of estimation type as per wikipedia

Method Detail

estimate back to summary

protected double estimate(final double[] work, final int[] pivotsHeap, final double pos, final int length, final KthSelector selector)

Estimation based on K^th selection. This may be overridden in specific enums to compute slightly different estimations.

Parameters

work:double[]: array of numbers to be used for finding the percentile
pivotsHeap:int[]: an earlier populated cache if exists; will be used
pos:double: indicated positional index prior computed from calling index(double, int)
length:int: size of array considered
selector:KthSelector: a KthSelector used for pivoting during search

Returns:double

estimated percentile

evaluate back to summary

protected double evaluate(final double[] work, final int[] pivotsHeap, final double p, final KthSelector selector)

Evaluate method to compute the percentile for a given bounded array using earlier computed pivots heap.
This basically calls the index and then estimate functions to return the estimated percentile value.

Parameters

work:double[]: array of numbers to be used for finding the percentile
pivotsHeap:int[]: a prior cached heap which can speed up estimation
p:double: the p^th quantile to be computed
selector:KthSelector: a KthSelector used for pivoting during search

Returns:double

estimated percentile

Exceptions

OutOfRangeException:: if p is out of range
NullArgumentException:: if work array is null

evaluate back to summary

public double evaluate(final double[] work, final double p, final KthSelector selector)

Evaluate method to compute the percentile for a given bounded array. This basically calls the index and then estimate functions to return the estimated percentile value. Please note that this method does not make use of cached pivots.

Parameters

work:double[]: array of numbers to be used for finding the percentile
p:double: the p^th quantile to be computed
selector:KthSelector: a KthSelector used for pivoting during search

Returns:double

estimated percentile

Exceptions

OutOfRangeException:: if length or p is out of range
NullArgumentException:: if work array is null

getName

back to summary

pack-priv String getName()

Gets the name of the enum

Returns:String: the name

index back to summary

protected abstract double index(final double p, final int length)

Finds the index of array that can be used as starting index to estimate percentile. The calculation of index calculation is specific to each EstimationType.

Parameters

p:double: the p^th quantile
length:int: the total number of array elements in the work array

Returns:double

a computed real valued index as explained in the wikipedia

valueOf	back to summary
public static Percentile.EstimationType valueOf(String name)

values	back to summary
public static Percentile.EstimationType[] values()

public Class Percentile

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

public sealed Enum Percentile.EstimationType

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail