position bias removal support (#77)

Author: shuttie

README.md

@@ -106,7 +106,7 @@ So if you do `parameters = "label=some_column_name"`, it will be ignored by the
 `createFromMat`
 * to set these magical columns, you need to explicitly call `LGBMDataset.setField()` method.
 * `label` and `weight` columns [must be](https://lightgbm.readthedocs.io/en/latest/C-API.html#c.LGBM_DatasetSetField) `float[]`
-* `group` column [must be](https://lightgbm.readthedocs.io/en/latest/C-API.html#c.LGBM_DatasetSetField) `int[]`
+* `group` and `position` column [must be](https://lightgbm.readthedocs.io/en/latest/C-API.html#c.LGBM_DatasetSetField) `int[]`
 
 A full example of loading dataset from a matrix for a cancer dataset:
 ```java
@@ -200,6 +200,25 @@ for (int i=0; i<10; i++) {
 }
 ```
 
+### Position bias removal
+
+LightGBM 4.1+ can perform a [position-bias aware LTR/LambdaMART](https://lightgbm.readthedocs.io/en/latest/Advanced-Topics.html#support-for-position-bias-treatment) training. To perform it with lightgbm4j you need to explicitly define the `position` field as described in the upstream LightGBM docs:
+
+```java
+float[] matrix = new float[] {
+        // query group 1
+        1.0f, 2.0f, // doc1
+        3.0f, 4.0f, // doc2
+        // query group 2
+        1.0f, 2.0f, // doc1
+        3.0f, 4.0f}; // doc2
+LGBMDataset ds = LGBMDataset.createFromMat(matrix, 4, 2, true, "", null);
+ds.setField("label", new float[] {1.0, 0.0, 1.0, 0.0}); // set relevance labels
+ds.setField("group", new int[] {2, 2}); // set document-to-group mapping
+ds.setField("position", new int[] {0, 1, 2, 3, 0, 1, 2, 3}); // bias classes
+LGBMBooster booster = LGBMBooster.create(ds, "objective=lambdarank");
+```
+
 ### Custom objectives
 
 LightGBM4j supports using custom objective functions, but it doesn't provide any high-level wrappers as python API does. 

src/main/java/io/github/metarank/lightgbm4j/LGBMDataset.java

@@ -198,7 +198,8 @@ public void setField(String fieldName, double[] data) throws LGBMException {
      * @throws LGBMException
      */
     public void setField(String fieldName, int[] data) throws LGBMException {
-        if (!fieldName.equals("group")) throw new LGBMException("only group field can be int[]");
+        if (fieldName.equals("label")) throw new LGBMException("label can only be float[]");
+        if (fieldName.equals("weight")) throw new LGBMException("weight can only be float[]");
         SWIGTYPE_p_int dataBuffer = new_intArray(data.length);
         for (int i = 0; i < data.length; i++) {
             intArray_setitem(dataBuffer, i, data[i]);

src/test/java/io/github/metarank/lightgbm4j/RankingIntegrationTest.java

@@ -14,8 +14,23 @@
 public class RankingIntegrationTest {
     @Test
     public void testLetor() throws LGBMException, IOException {
-        LGBMDataset train = datasetFromResource("/mq2008/train.txt.gz", null);
-        LGBMDataset test = datasetFromResource("/mq2008/test.txt.gz", train);
+        LGBMDataset train = datasetFromResource("/mq2008/train.txt.gz", null, false);
+        LGBMDataset test = datasetFromResource("/mq2008/test.txt.gz", train, false);
+        trainBooster(train, test);
+        train.close();
+        test.close();
+    }
+
+    @Test
+    public void testLetorPosition() throws LGBMException, IOException {
+        LGBMDataset train = datasetFromResource("/mq2008/train.txt.gz", null, true);
+        LGBMDataset test = datasetFromResource("/mq2008/test.txt.gz", train, true);
+        trainBooster(train, test);
+        train.close();
+        test.close();
+    }
+
+    public void trainBooster(LGBMDataset train, LGBMDataset test) throws LGBMException, IOException  {
         LGBMBooster booster = LGBMBooster.create(train, "objective=lambdarank metric=ndcg lambdarank_truncation_level=10 max_depth=5 learning_rate=0.1 num_leaves=8");
         booster.addValidData(test);
         for (int i=0; i<100; i++) {
@@ -30,12 +45,10 @@ public void testLetor() throws LGBMException, IOException {
         assertTrue(names.length > 0);
         assertTrue(weights.length > 0);
         booster.close();
-        train.close();
-        test.close();
     }
 
 
-    private static LGBMDataset datasetFromResource(String file, LGBMDataset parent) throws LGBMException, IOException {
+    private static LGBMDataset datasetFromResource(String file, LGBMDataset parent, boolean withPosition) throws LGBMException, IOException {
         BufferedReader reader = new BufferedReader(new InputStreamReader(new GZIPInputStream(RankingIntegrationTest.class.getResourceAsStream(file))));
         ArrayList<String> lines = reader.lines().map(line -> {
             int commentIndex = line.indexOf('#');
@@ -65,18 +78,21 @@ private static LGBMDataset datasetFromResource(String file, LGBMDataset parent)
         double[] features = new double[maxFeatureId * rows];
         float[] labels = new float[rows];
         int[] groups = new int[queries];
+        int[] positions = new int[rows];
         String[] featureNames = new String[maxFeatureId];
         for (int i=1; i <= maxFeatureId; i++) {
             featureNames[i-1] = "f"+i;
         }
         int lastGroup = Integer.MIN_VALUE;
         int lastCount = 0;
         int groupIndex = 0;
+        int position = 0;
         for (int row = 0; row < rows; row++) {
             String line = lines.get(row);
             String[] tokens = line.split(" ");
             float label = Float.parseFloat(tokens[0]);
             labels[row] = label;
+            positions[row] = position;
             int group = Integer.parseInt(tokens[1].split(":")[1]);
             if (group != lastGroup) {
                 // next query
@@ -87,6 +103,7 @@ private static LGBMDataset datasetFromResource(String file, LGBMDataset parent)
                 }
                 lastGroup = group;
                 lastCount = 1;
+                position = 0;
             } else {
                 lastCount++;
             }
@@ -97,6 +114,7 @@ private static LGBMDataset datasetFromResource(String file, LGBMDataset parent)
                 double value = Double.parseDouble(feature[1]);
                 features[row * maxFeatureId + id] = value;
             }
+            position++;
         }
         groups[groupIndex] = lastCount;
 
@@ -106,6 +124,7 @@ private static LGBMDataset datasetFromResource(String file, LGBMDataset parent)
         dataset.setFeatureNames(featureNames);
         dataset.setField("label", labels);
         dataset.setField("group", groups);
+        if (withPosition) dataset.setField("position", positions);
         return dataset;
     }