Class Quantile
- java.lang.Object
-
- org.apache.commons.statistics.descriptive.Quantile
-
public final class Quantile extends java.lang.Object
Provides quantile computation.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)
forNaN
values. If aNaN
occurs in the selected positions in the fully sorted values then the result isNaN
.The
NaNPolicy
can be used to change the behaviour onNaN
values.Instances of this class are immutable and thread-safe.
- Since:
- 1.1
- See Also:
with(NaNPolicy)
, Quantile (Wikipedia)
- The result is
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
Quantile.EstimationMethod
Estimation methods for a quantile.
-
Field Summary
Fields Modifier and Type Field Description private boolean
copy
Flag to indicate if the data should be copied.private static Quantile
DEFAULT
Default instance.private Quantile.EstimationMethod
estimationType
Estimation type used to determine the value from the quantile.private static java.lang.String
INVALID_NUMBER_OF_PROBABILITIES
Message when the number of probabilities in a range is not valid.private static java.lang.String
INVALID_PROBABILITY
Message when the probability is not in the range[0, 1]
.private static java.lang.String
INVALID_SIZE
Message when the size is not valid.private NaNPolicy
nanPolicy
NaN policy for floating point data.private NaNTransformer
nanTransformer
Transformer for NaN data.private static java.lang.String
NO_PROBABILITIES_SPECIFIED
Message when no probabilities are provided for the varargs method.
-
Constructor Summary
Constructors Modifier Constructor Description private
Quantile(boolean copy, NaNPolicy nanPolicy, Quantile.EstimationMethod estimationType)
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description private 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, java.util.function.IntToDoubleFunction values, double p)
Evaluate thep
-th quantile of the values.double[]
evaluate(int n, java.util.function.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]
.Quantile
with(NaNPolicy v)
Return an instance with the configuredNaNPolicy
.Quantile
with(Quantile.EstimationMethod v)
Return an instance with the configuredQuantile.EstimationMethod
.Quantile
withCopy(boolean v)
Return an instance with the configured copy behaviour.static Quantile
withDefaults()
Return a new instance with the default options.
-
-
-
Field Detail
-
INVALID_PROBABILITY
private static final java.lang.String INVALID_PROBABILITY
Message when the probability is not in the range[0, 1]
.- See Also:
- Constant Field Values
-
NO_PROBABILITIES_SPECIFIED
private static final java.lang.String NO_PROBABILITIES_SPECIFIED
Message when no probabilities are provided for the varargs method.- See Also:
- Constant Field Values
-
INVALID_SIZE
private static final java.lang.String INVALID_SIZE
Message when the size is not valid.- See Also:
- Constant Field Values
-
INVALID_NUMBER_OF_PROBABILITIES
private static final java.lang.String INVALID_NUMBER_OF_PROBABILITIES
Message when the number of probabilities in a range is not valid.- See Also:
- Constant Field Values
-
DEFAULT
private static final Quantile DEFAULT
Default instance. Method 8 is recommended by Hyndman and Fan.
-
copy
private final boolean copy
Flag to indicate if the data should be copied.
-
nanPolicy
private final NaNPolicy nanPolicy
NaN policy for floating point data.
-
nanTransformer
private final NaNTransformer nanTransformer
Transformer for NaN data.
-
estimationType
private final Quantile.EstimationMethod estimationType
Estimation type used to determine the value from the quantile.
-
-
Constructor Detail
-
Quantile
private Quantile(boolean copy, NaNPolicy nanPolicy, Quantile.EstimationMethod estimationType)
- 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 Detail
-
withDefaults
public static Quantile 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(boolean)
,with(NaNPolicy)
,with(EstimationMethod)
-
withCopy
public Quantile withCopy(boolean v)
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
public Quantile with(NaNPolicy v)
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
public Quantile with(Quantile.EstimationMethod v)
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:
java.lang.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:
java.lang.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:
java.lang.IllegalArgumentException
- if the probabilityp
is not in the range[0, 1]
- See Also:
evaluate(double[], double...)
-
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:
java.lang.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:
java.lang.IllegalArgumentException
- if the probabilityp
is not in the range[0, 1]
- See Also:
evaluate(int[], double...)
-
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:
java.lang.IllegalArgumentException
- if any probabilityp
is not in the range[0, 1]
; or no probabilities are specified.
-
evaluate
public double evaluate(int n, java.util.function.IntToDoubleFunction values, double p)
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:
java.lang.IllegalArgumentException
- ifsize < 0
; or if the probabilityp
is not in the range[0, 1]
.
-
evaluate
public double[] evaluate(int n, java.util.function.IntToDoubleFunction values, double... p)
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:
java.lang.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:
java.lang.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:
java.lang.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:
java.lang.IllegalArgumentException
- ifsize < 0
-
checkNumberOfProbabilities
private static void checkNumberOfProbabilities(int n)
Check the number of probabilitiesn
is strictly positive.- Parameters:
n
- Number of probabilities.- Throws:
java.lang.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
-
-