Class Quantile
- java.lang.Object
-
- org.apache.commons.statistics.descriptive.Quantile
-
public final class Quantile extends Object
Provides quantile computation.For values of length
n:- The result is
NaNifn = 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)forNaNvalues. If aNaNoccurs in the selected positions in the fully sorted values then the result isNaN.The
NaNPolicycan be used to change the behaviour onNaNvalues.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 classQuantile.EstimationMethodEstimation methods for a quantile.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description doubleevaluate(double[] values, double p)Evaluate thep-th quantile of the values.double[]evaluate(double[] values, double... p)Evaluate thep-th quantiles of the values.doubleevaluate(int[] values, double p)Evaluate thep-th quantile of the values.double[]evaluate(int[] values, double... p)Evaluate thep-th quantiles of the values.doubleevaluate(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)Generatenevenly spaced probabilities in the range[0, 1].static double[]probabilities(int n, double p1, double p2)Generatenevenly spaced probabilities in the range[p1, p2].Quantilewith(NaNPolicy v)Return an instance with the configuredNaNPolicy.Quantilewith(Quantile.EstimationMethod v)Return an instance with the configuredQuantile.EstimationMethod.QuantilewithCopy(boolean v)Return an instance with the configured copy behaviour.static QuantilewithDefaults()Return a new instance with the default options.
-
-
-
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
NaNvalues 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. Iffalsethen 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)forNaNvalues:NaNis considered greater than all other values, and allNaNvalues are equal. TheNaNPolicychanges the computation of the statistic in the presence ofNaNvalues.NaNPolicy.INCLUDE:NaNvalues are moved to the end of the data; the size of the data includes theNaNvalues and the quantile will beNaNif any value used for quantile interpolation isNaN.NaNPolicy.EXCLUDE:NaNvalues are moved to the end of the data; the size of the data excludes theNaNvalues and the quantile will never beNaNfor non-zero size. If all data areNaNthen the size is zero and the result isNaN.NaNPolicy.ERROR: An exception is raised if the data containsNaNvalues.
Note that the result is identical for all policies if no
NaNvalues 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)
Generatenevenly 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)
Generatenevenly 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
copythe 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 probabilitypis 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
copythe input data.- Parameters:
values- Values.p- Probabilities for the quantiles to compute.- Returns:
- the quantiles
- Throws:
IllegalArgumentException- if any probabilitypis 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
copythe 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 probabilitypis 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
copythe input data.- Parameters:
values- Values.p- Probabilities for the quantiles to compute.- Returns:
- the quantiles
- Throws:
IllegalArgumentException- if any probabilitypis not in the range[0, 1]; or no probabilities are specified.
-
evaluate
public double evaluate(int n, 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:
IllegalArgumentException- ifsize < 0; or if the probabilitypis not in the range[0, 1].
-
evaluate
public double[] evaluate(int n, 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:
IllegalArgumentException- ifsize < 0; if any probabilitypis not in the range[0, 1]; or no probabilities are specified.
-
-