diff --git a/commons-math-legacy/src/main/java/org/apache/commons/math4/legacy/stat/StatUtils.java b/commons-math-legacy/src/main/java/org/apache/commons/math4/legacy/stat/StatUtils.java index 841c46564..824d0567d 100644 --- a/commons-math-legacy/src/main/java/org/apache/commons/math4/legacy/stat/StatUtils.java +++ b/commons-math-legacy/src/main/java/org/apache/commons/math4/legacy/stat/StatUtils.java @@ -41,7 +41,7 @@ public final class StatUtils { /** percentile. */ - private static final Quantile QUANTILE = Quantile.withDefaults().with(EstimationMethod.HF6).withCopy(false); + private static final Quantile QUANTILE = Quantile.withDefaults().with(EstimationMethod.HF6).withCopy(true); /** * Private Constructor. @@ -477,6 +477,13 @@ public static double min(final double[] values, final int begin, final int lengt * *

* See Commons Statistics {@link Quantile} for a description of the percentile estimation algorithm used. + *

+ * The percentile is computed on a copy of the input so the order of + * values is not changed. The copy is made on every call. To + * compute several percentiles of the same data use a single call of + * {@link Quantile#evaluate(double[], double...)} with all the probabilities + * (scaled from 0 - 1), using {@link EstimationMethod#HF6} to match this method, + * and {@link Quantile#withCopy(boolean) withCopy(false)} if the input may be reordered. * * @param values input array of values * @param p the percentile value to compute @@ -504,6 +511,14 @@ public static double percentile(final double[] values, final double p) throws Ma * *

* See Commons Statistics {@link Quantile} for a description of the percentile estimation algorithm used. + *

+ * The percentile is computed on a copy of the specified range so the order of + * values is not changed. The copy is made on every call. To + * compute several percentiles of the same data use a single call of + * {@link Quantile#evaluateRange(double[], int, int, double...)} with all the + * probabilities (scaled from 0 - 1), using {@link EstimationMethod#HF6} to match + * this method, and {@link Quantile#withCopy(boolean) withCopy(false)} if the input + * may be reordered. * * @param values array of input values * @param p the percentile to compute diff --git a/commons-math-legacy/src/main/java/org/apache/commons/math4/legacy/stat/descriptive/DescriptiveStatistics.java b/commons-math-legacy/src/main/java/org/apache/commons/math4/legacy/stat/descriptive/DescriptiveStatistics.java index 518488495..b3cbff667 100644 --- a/commons-math-legacy/src/main/java/org/apache/commons/math4/legacy/stat/descriptive/DescriptiveStatistics.java +++ b/commons-math-legacy/src/main/java/org/apache/commons/math4/legacy/stat/descriptive/DescriptiveStatistics.java @@ -437,6 +437,23 @@ public double getElement(int index) { *

  • at least one value must be stored (returns Double.NaN * otherwise)
  • * + *

    + * The default implementation computes the percentile on a copy of the + * stored values so the order returned by {@link #getValues()} is preserved. + * The copy and the selection are repeated on every call, even if the stored + * values have not changed. To compute several percentiles of the same data, + * get the values once and pass all the probabilities (scaled from 0 - 1) to + * a single call of Commons Statistics + * {@link org.apache.commons.statistics.descriptive.Quantile#evaluate(double[], double...) + * Quantile.evaluate}. The same estimation as this method is obtained with: + *

    +     * Quantile.withDefaults()
    +     *         .with(Quantile.EstimationMethod.HF6)
    +     *         .withCopy(false)
    +     *         .evaluate(stats.getValues(), 0.25, 0.5, 0.75);
    +     * 
    + *

    + * {@code withCopy(false)} is safe here since {@link #getValues()} returns a copy. * * @param p the requested percentile (scaled from 0 - 100) * @return An estimate for the pth percentile of the stored data diff --git a/commons-math-legacy/src/main/java/org/apache/commons/math4/legacy/stat/descriptive/Statistics.java b/commons-math-legacy/src/main/java/org/apache/commons/math4/legacy/stat/descriptive/Statistics.java index 9445ea4c3..a097e7df0 100644 --- a/commons-math-legacy/src/main/java/org/apache/commons/math4/legacy/stat/descriptive/Statistics.java +++ b/commons-math-legacy/src/main/java/org/apache/commons/math4/legacy/stat/descriptive/Statistics.java @@ -316,7 +316,7 @@ static Sum getInstance() { static final class Percentile implements UnivariateStatistic { /** Delegate percentile implementation. */ private static final Quantile QUANTILE = - Quantile.withDefaults().with(EstimationMethod.HF6).withCopy(false); + Quantile.withDefaults().with(EstimationMethod.HF6).withCopy(true); /** Probability. */ private double p; diff --git a/commons-math-legacy/src/test/java/org/apache/commons/math4/legacy/stat/StatUtilsTest.java b/commons-math-legacy/src/test/java/org/apache/commons/math4/legacy/stat/StatUtilsTest.java index b5a8dcd5c..5bc4bfb65 100644 --- a/commons-math-legacy/src/test/java/org/apache/commons/math4/legacy/stat/StatUtilsTest.java +++ b/commons-math-legacy/src/test/java/org/apache/commons/math4/legacy/stat/StatUtilsTest.java @@ -456,6 +456,14 @@ public void testPercentile() { TestUtils.assertEquals(2.5, StatUtils.percentile(x, 1, 3, 62.5), TOLERANCE); } + @Test + public void testPercentileDoesNotModifyInput() { + final double[] x = {THREE, ONE, TWO, TWO}; + StatUtils.percentile(x, 50); + StatUtils.percentile(x, 1, 3, 50); + Assert.assertArrayEquals(new double[] {THREE, ONE, TWO, TWO}, x, 0); + } + @Test public void testDifferenceStats() { double sample1[] = {1d, 2d, 3d, 4d}; diff --git a/commons-math-legacy/src/test/java/org/apache/commons/math4/legacy/stat/descriptive/DescriptiveStatisticsTest.java b/commons-math-legacy/src/test/java/org/apache/commons/math4/legacy/stat/descriptive/DescriptiveStatisticsTest.java index c47e7f57f..0fdfba57c 100644 --- a/commons-math-legacy/src/test/java/org/apache/commons/math4/legacy/stat/descriptive/DescriptiveStatisticsTest.java +++ b/commons-math-legacy/src/test/java/org/apache/commons/math4/legacy/stat/descriptive/DescriptiveStatisticsTest.java @@ -125,6 +125,22 @@ public void testGetValues() { Assert.assertEquals(12.0, stats.getElement(88), 1.0e-10); } + @Test + public void testPercentileDoesNotReorderValues() { + DescriptiveStatistics stats = createDescriptiveStatistics(); + stats.setWindowSize(5); + for (double v : new double[] {5, 4, 3, 2, 1}) { + stats.addValue(v); + } + Assert.assertEquals(3, stats.getPercentile(50), 0); + // toString() reports the median + Assert.assertNotNull(stats.toString()); + Assert.assertArrayEquals(new double[] {5, 4, 3, 2, 1}, stats.getValues(), 0); + // The oldest value is discarded + stats.addValue(100); + Assert.assertArrayEquals(new double[] {4, 3, 2, 1, 100}, stats.getValues(), 0); + } + @Test public void testQuadraticMean() { final double[] values = { 1.2, 3.4, 5.6, 7.89 };