SeaseLtd#109: Add k, grade parameters to RR constructor; use floating…

… point values for grading.

rre-core/src/main/java/io/sease/rre/core/domain/metrics/impl/ReciprocalRank.java

@@ -16,6 +16,7 @@
  */
 package io.sease.rre.core.domain.metrics.impl;
 
+import com.fasterxml.jackson.annotation.JsonProperty;
 import com.fasterxml.jackson.databind.JsonNode;
 import io.sease.rre.Func;
 import io.sease.rre.core.domain.metrics.Metric;
@@ -24,6 +25,7 @@
 import java.math.BigDecimal;
 import java.math.RoundingMode;
 import java.util.Map;
+import java.util.Optional;
 
 /**
  * The reciprocal rank of a query response is the multiplicative inverse of the rank of the first correct answer.
@@ -32,25 +34,57 @@
  * @since 1.0
  */
 public class ReciprocalRank extends Metric {
+
+    private final int k;
+    private final BigDecimal maxgrade;
+    private final BigDecimal fairgrade;
+
     /**
-     * Builds a new ReciprocalRank at X metric.
+     * Builds a new ReciprocalRank at 10 metric.
      */
     public ReciprocalRank() {
-        super("RR@10");
+        this(10, null, null);
+    }
+
+    /**
+     * Builds a new Reciprocal Rank at K metric.
+     *
+     * @param k the top k reference elements used for building the measure.
+     * @param maxgrade the maximum grade available when judging documents. If
+     *                 {@code null}, will default to {@link Metric#DEFAULT_MAX_GRADE}.
+     * @param defaultgrade the default grade to use when judging documents. If
+     *                     {@code null}, will default to either {@code maxgrade / 2}
+     *                     or {@link Metric#DEFAULT_MISSING_GRADE}, depending
+     *                     whether or not {@code maxgrade} has been specified.
+     */
+    public ReciprocalRank(@JsonProperty("k") final int k,
+                          @JsonProperty("maxgrade") final Float maxgrade,
+                          @JsonProperty("defaultgrade") final Float defaultgrade) {
+        super("RR@" + k);
+        this.k = k;
+        if (maxgrade == null) {
+            this.maxgrade = DEFAULT_MAX_GRADE;
+            this.fairgrade = Optional.ofNullable(defaultgrade).map(BigDecimal::valueOf).orElse(DEFAULT_MISSING_GRADE);
+        } else {
+            this.maxgrade = BigDecimal.valueOf(maxgrade);
+            this.fairgrade = Optional.ofNullable(defaultgrade).map(BigDecimal::valueOf).orElseGet(() -> this.maxgrade.divide(BigDecimal.valueOf(2), 8, RoundingMode.HALF_UP));
+        }
     }
 
     @Override
     public ValueFactory createValueFactory(final String version) {
         return new ValueFactory(this, version) {
             private int rank;
-            private int maxGain;
+            private BigDecimal maxGain = BigDecimal.ZERO;
+            private int totalDocs = 0;
 
             @Override
             public void collect(final Map<String, Object> hit, final int rank, final String version) {
+                if (++totalDocs > k) return;
                 judgment(id(hit))
                         .ifPresent(hitData -> {
-                            final int gain = Func.gainOrRatingNode(hitData).map(JsonNode::asInt).orElse(2);
-                            if (gain > maxGain) {
+                            final BigDecimal gain = Func.gainOrRatingNode(hitData).map(JsonNode::decimalValue).orElse(fairgrade);
+                            if (gain.compareTo(maxGain) > 0) {
                                 this.rank = rank;
                                 this.maxGain = gain;
                             }

rre-core/src/test/java/io.sease.rre.core.domain.metrics.impl/ReciprocalRankTestCase.java

@@ -27,6 +27,7 @@
 import java.util.concurrent.atomic.AtomicInteger;
 
 import static io.sease.rre.core.TestData.A_VERSION;
+import static io.sease.rre.core.TestData.FIFTEEN_SEARCH_HITS;
 import static java.util.Arrays.stream;
 import static org.junit.Assert.assertEquals;
 
@@ -174,4 +175,22 @@ public void firstRelevantResultAtSecondPosition() {
 
         assertEquals(0.5d, cut.valueFactory(A_VERSION).value().doubleValue(), 0);
     }
+
+    /**
+     * If the first relevant result is outside the first K results, the value
+     * should be 0.
+     */
+    @Test
+    public void firstRelevantResultOutsideKResults() {
+        final ObjectNode judgements = mapper.createObjectNode();
+        stream(FIFTEEN_SEARCH_HITS).skip(11).limit(1).forEach(docid -> judgements.set(docid, createJudgmentNode(3)));
+        cut.setRelevantDocuments(judgements);
+
+        cut.setTotalHits(FIFTEEN_SEARCH_HITS.length, A_VERSION);
+        stream(FIFTEEN_SEARCH_HITS)
+                .map(this::searchHit)
+                .forEach(hit -> cut.collect(hit, counter.incrementAndGet(), A_VERSION));
+
+        assertEquals(0.0d, cut.valueFactory(A_VERSION).value().doubleValue(), 0);
+    }
 }