You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by ah...@apache.org on 2022/12/06 17:30:29 UTC
[commons-statistics] branch master updated: Add ranking module to the user guide.
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 <ah...@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>