This is an automated email from the ASF dual-hosted git repository. aherbert pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/commons-statistics.git
The following commit(s) were added to refs/heads/master by this push: new b078559 Add ranking module to the user guide. b078559 is described below commit b0785598914123f682280657aae5cc5b3b963594 Author: aherbert <aherb...@apache.org> AuthorDate: Tue Dec 6 17:29:34 2022 +0000 Add ranking module to the user guide. --- .../commons/statistics/ranking/UserGuideTest.java | 48 ++++++++++++++++-- src/site/site.xml | 1 + src/site/xdoc/userguide/index.xml | 58 +++++++++++++++++++++- 3 files changed, 103 insertions(+), 4 deletions(-) diff --git a/commons-statistics-ranking/src/test/java/org/apache/commons/statistics/ranking/UserGuideTest.java b/commons-statistics-ranking/src/test/java/org/apache/commons/statistics/ranking/UserGuideTest.java index 03c43d1..123174a 100644 --- a/commons-statistics-ranking/src/test/java/org/apache/commons/statistics/ranking/UserGuideTest.java +++ b/commons-statistics-ranking/src/test/java/org/apache/commons/statistics/ranking/UserGuideTest.java @@ -17,6 +17,10 @@ package org.apache.commons.statistics.ranking; +import java.util.Arrays; +import java.util.SplittableRandom; +import org.apache.commons.rng.UniformRandomProvider; +import org.apache.commons.rng.simple.RandomSource; import org.junit.jupiter.api.Assertions; import org.junit.jupiter.api.Test; @@ -25,10 +29,48 @@ import org.junit.jupiter.api.Test; */ class UserGuideTest { @Test - void testRanking() { - NaturalRanking ranking = new NaturalRanking(); + void testRanking1() { + final NaturalRanking ranking = new NaturalRanking(); Assertions.assertArrayEquals(new double[] {1, 2, 3, 4}, ranking.apply(new double[] {5, 6, 7, 8})); Assertions.assertArrayEquals(new double[] {4, 1, 3, 2}, ranking.apply(new double[] {8, 5, 7, 6})); - Assertions.assertArrayEquals(new double[] {2.5, 1, 2.5, 4}, ranking.apply(new double[] {6, 5, 6, 7})); + } + + @Test + void testRanking2() { + final double[] data = {8, 5, Double.NaN, 6}; + final NaturalRanking ranking1 = new NaturalRanking(); + Assertions.assertThrows(IllegalArgumentException.class, () -> ranking1.apply(data)); + Assertions.assertArrayEquals(new double[] {4, 2, 1, 3}, new NaturalRanking(NaNStrategy.MINIMAL).apply(data)); + Assertions.assertArrayEquals(new double[] {3, 1, 4, 2}, new NaturalRanking(NaNStrategy.MAXIMAL).apply(data)); + Assertions.assertArrayEquals(new double[] {3, 1, 2}, new NaturalRanking(NaNStrategy.REMOVED).apply(data)); + Assertions.assertArrayEquals(new double[] {3, 1, Double.NaN, 2}, new NaturalRanking(NaNStrategy.FIXED).apply(data)); + final NaturalRanking ranking2 = new NaturalRanking(NaNStrategy.FAILED); + Assertions.assertThrows(IllegalArgumentException.class, () -> ranking2.apply(data)); + } + + @Test + void testRanking3() { + final double[] data = {7, 5, 7, 6}; + Assertions.assertArrayEquals(new double[] {3.5, 1, 3.5, 2}, new NaturalRanking().apply(data)); + Assertions.assertArrayEquals(new double[] {3, 1, 4, 2}, new NaturalRanking(TiesStrategy.SEQUENTIAL).apply(data)); + Assertions.assertArrayEquals(new double[] {3, 1, 3, 2}, new NaturalRanking(TiesStrategy.MINIMUM).apply(data)); + Assertions.assertArrayEquals(new double[] {4, 1, 4, 2}, new NaturalRanking(TiesStrategy.MAXIMUM).apply(data)); + Assertions.assertArrayEquals(new double[] {3.5, 1, 3.5, 2}, new NaturalRanking(TiesStrategy.AVERAGE).apply(data)); + final double[] r = new NaturalRanking(TiesStrategy.RANDOM).apply(data); + Assertions.assertTrue(Arrays.equals(new double[] {3, 1, 4, 2}, r) || Arrays.equals(new double[] {4, 1, 3, 2}, r)); + } + + @Test + void testRanking4() { + final double[] data = {7, 5, 7, 6}; + final double[] r1 = new NaturalRanking(TiesStrategy.RANDOM).apply(data); + final double[] r2 = new NaturalRanking(new SplittableRandom()::nextLong).apply(data); + final UniformRandomProvider rng = RandomSource.KISS.create(); + final double[] r3 = new NaturalRanking(rng::nextLong).apply(data); + final double[] expected1 = {3, 1, 4, 2}; + final double[] expected2 = {4, 1, 3, 2}; + Assertions.assertTrue(Arrays.equals(expected1, r1) || Arrays.equals(expected2, r1)); + Assertions.assertTrue(Arrays.equals(expected1, r2) || Arrays.equals(expected2, r2)); + Assertions.assertTrue(Arrays.equals(expected1, r3) || Arrays.equals(expected2, r3)); } } diff --git a/src/site/site.xml b/src/site/site.xml index 3a65cb0..48ac04d 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -47,6 +47,7 @@ <item name="Overview" href="/userguide/index.html#overview"/> <item name="Example Modules" href="/userguide/index.html#example-modules"/> <item name="Probability Distributions" href="/userguide/index.html#distributions"/> + <item name="Ranking" href="/userguide/index.html#ranking"/> </menu> </body> diff --git a/src/site/xdoc/userguide/index.xml b/src/site/xdoc/userguide/index.xml index 49d4bea..47c7211 100644 --- a/src/site/xdoc/userguide/index.xml +++ b/src/site/xdoc/userguide/index.xml @@ -55,7 +55,9 @@ </li> </ul> </li> - + <li> + <a href="#ranking">Ranking</a> + </li> </ul> </section> @@ -332,6 +334,60 @@ double x2 = chi2.inverseSurvivalProbability(q); </p> </subsection> </section> + <section name="Ranking" id="ranking"> + <p> + The <code>commons-statistics-ranking</code> module provides rank transformations. + </p> + <p> + The <code>NaturalRanking</code> class provides a ranking based on the natural ordering + of floating-point values. Ranks are assigned to the input numbers in ascending order, + starting from 1. + </p> +<source class="prettyprint"> +NaturalRanking ranking = new NaturalRanking(); +ranking.apply(new double[] {5, 6, 7, 8}); // 1, 2, 3, 4 +ranking.apply(new double[] {8, 5, 7, 6}); // 4, 1, 3, 2 +</source> + <p> + The special case of <code>NaN</code> values are handled using the configured + <code>NaNStragegy</code>. The default is to raise an exception. + </p> +<source class="prettyprint"> +double[] data = new double[] {6, 5, Double.NaN, 7}; +new NaturalRanking().apply(data); // IllegalArgumentException +new NaturalRanking(NaNStrategy.MINIMAL).apply(data); // (4, 2, 1, 3) +new NaturalRanking(NaNStrategy.MAXIMAL).apply(data); // (3, 1, 4, 2) +new NaturalRanking(NaNStrategy.REMOVED).apply(data); // (3, 1, 2) +new NaturalRanking(NaNStrategy.FIXED).apply(data); // (3, 1, NaN, 2) +new NaturalRanking(NaNStrategy.FAILED).apply(data); // IllegalArgumentException +</source> + <p> + Ties are handled using the configured <code>TiesStragegy</code>. The default is to + use an average. + </p> +<source class="prettyprint"> +double[] data = new double[] {7, 5, 7, 6}; +new NaturalRanking(.apply(data); // (3.5, 1, 3.5, 2) +new NaturalRanking(TiesStrategy.SEQUENTIAL).apply(data); // (3, 1, 4, 2) +new NaturalRanking(TiesStrategy.MINIMUM).apply(data); // (3, 1, 3, 2) +new NaturalRanking(TiesStrategy.MAXIMUM).apply(data); // (4, 1, 4, 2) +new NaturalRanking(TiesStrategy.AVERAGE).apply(data); // (3.5, 1, 3.5, 2) +new NaturalRanking(TiesStrategy.RANDOM).apply(data); // (3, 1, 4, 2) or (4, 1, 3, 2) +</source> + <p> + The source of randomness defaults to a system supplied generator. The randomness can be + provided as a <code>LongSupplier</code> of random 64-bit values. + </p> +<source class="prettyprint"> +double[] data = new double[] {7, 5, 7, 6}; +new NaturalRanking(TiesStrategy.RANDOM).apply(data); +new NaturalRanking(new SplittableRandom()::nextLong).apply(data); +// From Commons RNG +UniformRandomProvider rng = RandomSource.KISS.create(); +new NaturalRanking(rng::nextLong).apply(data); +// ranks: (3, 1, 4, 2) or (4, 1, 3, 2) +</source> + </section> </body>