Class Quantile
For values of length n
:
- The result is
NaN
ifn = 0
. - The result is
values[0]
ifn = 1
. - Otherwise the result is computed using the
Quantile.EstimationMethod
.
Computation of multiple quantiles and will handle duplicate and unordered
probabilities. Passing ordered probabilities is recommended if the order is already
known as this can improve efficiency; for example using uniform spacing through the
array data, or to identify extreme values from the data such as [0.001, 0.999]
.
This implementation respects the ordering imposed by
Double.compare(double, double)
for NaN
values. If a NaN
occurs
in the selected positions in the fully sorted values then the result is NaN
.
The NaNPolicy
can be used to change the behaviour on NaN
values.
Instances of this class are immutable and thread-safe.
- Since:
- 1.1
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic enum
Estimation methods for a quantile. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final boolean
Flag to indicate if the data should be copied.private static final Quantile
Default instance.private final Quantile.EstimationMethod
Estimation type used to determine the value from the quantile.private static final String
Message when the number of probabilities in a range is not valid.private static final String
Message when the probability is not in the range[0, 1]
.private static final String
Message when the size is not valid.private final NaNPolicy
NaN policy for floating point data.private final NaNTransformer
Transformer for NaN data.private static final String
Message when no probabilities are provided for the varargs method. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprivate
Quantile
(boolean copy, NaNPolicy nanPolicy, Quantile.EstimationMethod estimationType) -
Method Summary
Modifier and TypeMethodDescriptionprivate static void
checkNumberOfProbabilities
(int n) Check the number of probabilitiesn
is strictly positive.private static void
checkProbabilities
(double... p) Check the probabilitiesp
are in the range[0, 1]
.private static void
checkProbability
(double p) Check the probabilityp
is in the range[0, 1]
.private static void
checkSize
(int n) Check thesize
is positive.private int[]
computeIndices
(int n, double[] p, double[] q) Compute the indices required for quantile interpolation.double
evaluate
(double[] values, double p) Evaluate thep
-th quantile of the values.double[]
evaluate
(double[] values, double... p) Evaluate thep
-th quantiles of the values.double
evaluate
(int[] values, double p) Evaluate thep
-th quantile of the values.double[]
evaluate
(int[] values, double... p) Evaluate thep
-th quantiles of the values.double
evaluate
(int n, IntToDoubleFunction values, double p) Evaluate thep
-th quantile of the values.double[]
evaluate
(int n, IntToDoubleFunction values, double... p) Evaluate thep
-th quantiles of the values.static double[]
probabilities
(int n) Generaten
evenly spaced probabilities in the range[0, 1]
.static double[]
probabilities
(int n, double p1, double p2) Generaten
evenly spaced probabilities in the range[p1, p2]
.Return an instance with the configuredNaNPolicy
.Return an instance with the configuredQuantile.EstimationMethod
.withCopy
(boolean v) Return an instance with the configured copy behaviour.static Quantile
Return a new instance with the default options.
-
Field Details
-
INVALID_PROBABILITY
Message when the probability is not in the range[0, 1]
.- See Also:
-
NO_PROBABILITIES_SPECIFIED
Message when no probabilities are provided for the varargs method.- See Also:
-
INVALID_SIZE
Message when the size is not valid.- See Also:
-
INVALID_NUMBER_OF_PROBABILITIES
Message when the number of probabilities in a range is not valid.- See Also:
-
DEFAULT
Default instance. Method 8 is recommended by Hyndman and Fan. -
copy
private final boolean copyFlag to indicate if the data should be copied. -
nanPolicy
NaN policy for floating point data. -
nanTransformer
Transformer for NaN data. -
estimationType
Estimation type used to determine the value from the quantile.
-
-
Constructor Details
-
Quantile
- Parameters:
copy
- Flag to indicate if the data should be copied.nanPolicy
- NaN policy.estimationType
- Estimation type used to determine the value from the quantile.
-
-
Method Details
-
withDefaults
Return a new instance with the default options.Note: The default options configure for processing in-place and including
NaN
values in the data. This is the most efficient mode and has the smallest memory consumption.- Returns:
- the quantile implementation
- See Also:
-
withCopy
Return an instance with the configured copy behaviour. Iffalse
then the input array will be modified by the call to evaluate the quantiles; otherwise the computation uses a copy of the data.- Parameters:
v
- Value.- Returns:
- an instance
-
with
Return an instance with the configuredNaNPolicy
.Note: This implementation respects the ordering imposed by
Double.compare(double, double)
forNaN
values:NaN
is considered greater than all other values, and allNaN
values are equal. TheNaNPolicy
changes the computation of the statistic in the presence ofNaN
values.NaNPolicy.INCLUDE
:NaN
values are moved to the end of the data; the size of the data includes theNaN
values and the quantile will beNaN
if any value used for quantile interpolation isNaN
.NaNPolicy.EXCLUDE
:NaN
values are moved to the end of the data; the size of the data excludes theNaN
values and the quantile will never beNaN
for non-zero size. If all data areNaN
then the size is zero and the result isNaN
.NaNPolicy.ERROR
: An exception is raised if the data containsNaN
values.
Note that the result is identical for all policies if no
NaN
values are present.- Parameters:
v
- Value.- Returns:
- an instance
-
with
Return an instance with the configuredQuantile.EstimationMethod
.- Parameters:
v
- Value.- Returns:
- an instance
-
probabilities
public static double[] probabilities(int n) Generaten
evenly spaced probabilities in the range[0, 1]
.1/(n + 1), 2/(n + 1), ..., n/(n + 1)
- Parameters:
n
- Number of probabilities.- Returns:
- the probabilities
- Throws:
IllegalArgumentException
- ifn < 1
-
probabilities
public static double[] probabilities(int n, double p1, double p2) Generaten
evenly spaced probabilities in the range[p1, p2]
.w = p2 - p1 p1 + w/(n + 1), p1 + 2w/(n + 1), ..., p1 + nw/(n + 1)
- Parameters:
n
- Number of probabilities.p1
- Lower probability.p2
- Upper probability.- Returns:
- the probabilities
- Throws:
IllegalArgumentException
- ifn < 1
; if the probabilities are not in the range[0, 1]
; orp2 <= p1
.
-
evaluate
public double evaluate(double[] values, double p) Evaluate thep
-th quantile of the values.Note: This method may partially sort the input values if not configured to
copy
the input data.Performance
It is not recommended to use this method for repeat calls for different quantiles within the same values. The
evaluate(double[], double...)
method should be used which provides better performance.- Parameters:
values
- Values.p
- Probability for the quantile to compute.- Returns:
- the quantile
- Throws:
IllegalArgumentException
- if the probabilityp
is not in the range[0, 1]
- See Also:
-
evaluate
public double[] evaluate(double[] values, double... p) Evaluate thep
-th quantiles of the values.Note: This method may partially sort the input values if not configured to
copy
the input data.- Parameters:
values
- Values.p
- Probabilities for the quantiles to compute.- Returns:
- the quantiles
- Throws:
IllegalArgumentException
- if any probabilityp
is not in the range[0, 1]
; or no probabilities are specified.
-
evaluate
public double evaluate(int[] values, double p) Evaluate thep
-th quantile of the values.Note: This method may partially sort the input values if not configured to
copy
the input data.Performance
It is not recommended to use this method for repeat calls for different quantiles within the same values. The
evaluate(int[], double...)
method should be used which provides better performance.- Parameters:
values
- Values.p
- Probability for the quantile to compute.- Returns:
- the quantile
- Throws:
IllegalArgumentException
- if the probabilityp
is not in the range[0, 1]
- See Also:
-
evaluate
public double[] evaluate(int[] values, double... p) Evaluate thep
-th quantiles of the values.Note: This method may partially sort the input values if not configured to
copy
the input data.- Parameters:
values
- Values.p
- Probabilities for the quantiles to compute.- Returns:
- the quantiles
- Throws:
IllegalArgumentException
- if any probabilityp
is not in the range[0, 1]
; or no probabilities are specified.
-
evaluate
Evaluate thep
-th quantile of the values.This method can be used when the values of known size are already sorted.
short[] x = ... Arrays.sort(x); double q = Quantile.withDefaults().evaluate(x.length, i -> x[i], 0.05);
- Parameters:
n
- Size of the values.values
- Values function.p
- Probability for the quantile to compute.- Returns:
- the quantile
- Throws:
IllegalArgumentException
- ifsize < 0
; or if the probabilityp
is not in the range[0, 1]
.
-
evaluate
Evaluate thep
-th quantiles of the values.This method can be used when the values of known size are already sorted.
short[] x = ... Arrays.sort(x); double[] q = Quantile.withDefaults().evaluate(x.length, i -> x[i], 0.25, 0.5, 0.75);
- Parameters:
n
- Size of the values.values
- Values function.p
- Probabilities for the quantiles to compute.- Returns:
- the quantiles
- Throws:
IllegalArgumentException
- ifsize < 0
; if any probabilityp
is not in the range[0, 1]
; or no probabilities are specified.
-
checkProbability
private static void checkProbability(double p) Check the probabilityp
is in the range[0, 1]
.- Parameters:
p
- Probability for the quantile to compute.- Throws:
IllegalArgumentException
- if the probability is not in the range[0, 1]
-
checkProbabilities
private static void checkProbabilities(double... p) Check the probabilitiesp
are in the range[0, 1]
.- Parameters:
p
- Probabilities for the quantiles to compute.- Throws:
IllegalArgumentException
- if any probabilitiesp
is not in the range[0, 1]
; or no probabilities are specified.
-
checkSize
private static void checkSize(int n) Check thesize
is positive.- Parameters:
n
- Size of the values.- Throws:
IllegalArgumentException
- ifsize < 0
-
checkNumberOfProbabilities
private static void checkNumberOfProbabilities(int n) Check the number of probabilitiesn
is strictly positive.- Parameters:
n
- Number of probabilities.- Throws:
IllegalArgumentException
- ifc < 1
-
computeIndices
private int[] computeIndices(int n, double[] p, double[] q) Compute the indices required for quantile interpolation.The zero-based interpolation index in
[0, n)
is saved into the working arrayq
for eachp
.- Parameters:
n
- Size of the data.p
- Probabilities for the quantiles to compute.q
- Working array for quantiles.- Returns:
- the indices
-