Adding a sample for LightGbm Ranking

Author: najeeb-kazmi

docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/BinaryClassification/LightGBMBinaryClassificationWithOptions.cs

@@ -1,5 +1,4 @@
 using Microsoft.ML.LightGBM;
-using Microsoft.ML.Transforms.Categorical;
 using static Microsoft.ML.LightGBM.Options;
 
 namespace Microsoft.ML.Samples.Dynamic

docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/Ranking/LightGBMRanking.cs

@@ -0,0 +1,42 @@
+using System;
+using System.Collections.Generic;
+using System.Text;
+
+namespace Microsoft.ML.Samples.Dynamic
+{
+    public class LightGbmRanking
+    {
+        // This example requires installation of additional nuget package <a href="https://www.nuget.org/packages/Microsoft.ML.LightGBM/">Microsoft.ML.LightGBM</a>.
+        public static void Example()
+        {
+            // Creating the ML.Net IHostEnvironment object, needed for the pipeline.
+            var mlContext = new MLContext();
+
+            // Download and featurize the train and validation datasets.
+            (var trainData, var validationData) = SamplesUtils.DatasetUtils.LoadFeaturizedMslrWeb10kTrainAndValidate(mlContext);
+
+            // Create the Estimator pipeline. For simplicity, we will train a small tree with 4 leaves and 2 boosting iterations.
+            var pipeline = mlContext.Ranking.Trainers.LightGbm(
+                labelColumn: "Label",
+                featureColumn: "Features",
+                groupIdColumn: "GroupId",
+                numLeaves: 4,
+                minDataPerLeaf: 10,
+                learningRate: 0.1,
+                numBoostRound: 2);
+
+            // Fit this Pipeline to the Training Data.
+            var model = pipeline.Fit(trainData);
+
+            // Evaluate how the model is doing on the test data.
+            var dataWithPredictions = model.Transform(validationData);
+
+            var metrics = mlContext.Ranking.Evaluate(dataWithPredictions, "Label", "GroupId");
+            SamplesUtils.ConsoleUtils.PrintMetrics(metrics);
+
+            // Output:
+            // DCG @N: 1.38, 3.11, 4.94
+            // NDCG @N: 7.13, 10.12, 12.62
+        }
+    }
+}

docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/Ranking/LightGBMRankingWithOptions.cs

@@ -0,0 +1,44 @@
+using Microsoft.ML.LightGBM;
+using static Microsoft.ML.LightGBM.Options;
+
+namespace Microsoft.ML.Samples.Dynamic
+{
+    public class LightGbmRankingWithOptions
+    {
+        // This example requires installation of additional nuget package <a href="https://www.nuget.org/packages/Microsoft.ML.LightGBM/">Microsoft.ML.LightGBM</a>.
+        public static void Example()
+        {
+            // Creating the ML.Net IHostEnvironment object, needed for the pipeline.
+            var mlContext = new MLContext();
+
+            // Download and featurize the train and validation datasets.
+            (var trainData, var validationData) = SamplesUtils.DatasetUtils.LoadFeaturizedMslrWeb10kTrainAndValidate(mlContext);
+
+            // Create the Estimator pipeline. For simplicity, we will train a small tree with 4 leaves and 2 boosting iterations.
+            var pipeline = mlContext.Ranking.Trainers.LightGbm(
+                new Options
+                {
+                    LabelColumn = "Label",
+                    FeatureColumn = "Features",
+                    GroupIdColumn = "GroupId",
+                    NumLeaves = 4,
+                    MinDataPerLeaf = 10,
+                    LearningRate = 0.1,
+                    NumBoostRound = 2
+                });
+
+            // Fit this Pipeline to the Training Data.
+            var model = pipeline.Fit(trainData);
+
+            // Evaluate how the model is doing on the test data.
+            var dataWithPredictions = model.Transform(validationData);
+
+            var metrics = mlContext.Ranking.Evaluate(dataWithPredictions, "Label", "GroupId");
+            SamplesUtils.ConsoleUtils.PrintMetrics(metrics);
+
+            // Output:
+            // DCG @N: 1.38, 3.11, 4.94
+            // NDCG @N: 7.13, 10.12, 12.62
+        }
+    }
+}

docs/samples/Microsoft.ML.Samples/Program.cs

@@ -6,7 +6,7 @@ internal static class Program
     {
         static void Main(string[] args)
         {
-            TakeRows.Example();
+            LightGbmRanking.Example();
         }
     }
 }

src/Microsoft.ML.Data/Evaluators/Metrics/RankerMetrics.cs

@@ -18,7 +18,7 @@ public sealed class RankerMetrics
         ///Array of discounted cumulative gains where i-th element represent DCG@i.
         /// <a href="https://en.wikipedia.org/wiki/Discounted_cumulative_gain">Discounted Cumulative gain</a>
         /// is the sum of the gains, for all the instances i, normalized by the natural logarithm of the instance + 1.
-        /// Note that unline the Wikipedia article, ML.Net uses the natural logarithm.
+        /// Note that unlike the Wikipedia article, ML.Net uses the natural logarithm.
         /// <image src="https://github.com/dotnet/machinelearning/tree/master/docs/images/DCG.png"></image>
         /// </summary>
         public double[] Dcg { get; }

src/Microsoft.ML.SamplesUtils/ConsoleUtils.cs

@@ -1,4 +1,5 @@
 using System;
+using System.Linq;
 using Microsoft.ML.Data;
 
 namespace Microsoft.ML.SamplesUtils
@@ -35,5 +36,15 @@ public static void PrintMetrics(RegressionMetrics metrics)
             Console.WriteLine($"RMS: {metrics.Rms:F2}");
             Console.WriteLine($"RSquared: {metrics.RSquared:F2}");
         }
+
+        /// <summary>
+        /// Pretty-print RankerMetrics objects.
+        /// </summary>
+        /// <param name="metrics">Ranker metrics.</param>
+        public static void PrintMetrics(RankerMetrics metrics)
+        {
+            Console.WriteLine($"DCG@N: {string.Join(", ", metrics.Dcg.Select(d => Math.Round(d, 2)).ToArray())}");
+            Console.WriteLine($"NDCG@N: {string.Join(", ", metrics.Ndcg.Select(d => Math.Round(d, 2)).ToArray())}");
+        }
     }
 }

src/Microsoft.ML.SamplesUtils/SamplesDatasetUtils.cs

@@ -146,6 +146,57 @@ public static IDataView LoadFeaturizedAdultDataset(MLContext mlContext)
             return featurizedData;
         }
 
+        public static string DownloadMslrWeb10kTrain()
+        {
+            var fileName = "MSLRWeb10KTrain720kRows.tsv";
+            if (!File.Exists(fileName))
+                Download("https://tlcresources.blob.core.windows.net/datasets/MSLR-WEB10K/MSLR-WEB10K_Fold1.TRAIN.500MB_720k-rows.tsv", fileName);
+            return fileName;
+        }
+
+        public static string DownloadMslrWeb10kValidate()
+        {
+            var fileName = "MSLRWeb10KValidate240kRows.tsv";
+            if (!File.Exists(fileName))
+                Download("https://tlcresources.blob.core.windows.net/datasets/MSLR-WEB10K/MSLR-WEB10K_Fold1.VALIDATE.160MB_240k-rows.tsv", fileName);
+            return fileName;
+        }
+
+        public static (IDataView, IDataView) LoadFeaturizedMslrWeb10kTrainAndValidate(MLContext mlContext)
+        {
+            // Download the training and validation files.
+            string trainDataFile = DownloadMslrWeb10kTrain();
+            string validationDataFile = DownloadMslrWeb10kValidate();
+
+            // Create the reader to read the data.
+            var reader = mlContext.Data.CreateTextLoader(
+                columns: new[]
+                {
+                    new TextLoader.Column("Label", DataKind.R4, 0),
+                    new TextLoader.Column("GroupId", DataKind.TX, 1),
+                    new TextLoader.Column("Features", DataKind.R4, new[] { new TextLoader.Range(2, 138) })
+                }
+            );
+
+            // Load the raw training and validation datasets.
+            var trainData = reader.Read(trainDataFile);
+            var validationData = reader.Read(validationDataFile);
+
+            // Create the featurization pipeline. First, hash the GroupId column.
+            var pipeline = mlContext.Transforms.Conversion.Hash("GroupId")
+                // Replace missing values in Features column with the default replacement value for its type.
+                .Append(mlContext.Transforms.ReplaceMissingValues("Features"));
+
+            // Fit the pipeline on the training data.
+            var fittedPipeline = pipeline.Fit(trainData);
+
+            // Use the fitted pipeline to transform the training and validation datasets.
+            var transformedTrainData = fittedPipeline.Transform(trainData);
+            var transformedValidationData = fittedPipeline.Transform(validationData);
+
+            return (transformedTrainData, transformedValidationData);
+        }
+
         /// <summary>
         /// Downloads the breast cancer dataset from the ML.NET repo.
         /// </summary>