Updating LightGBM Arguments (#2948)

* Breaking down the LightGBM options class into separate option classes for
each LightGBM trainer.
* Refactored the Boost Option classes
* Hides the interface for the Booster Parameter Factory
(IBoosterParameterFactory).

Fixes #2559 
Fixes #2618

Author: singlis

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

@@ -1,5 +1,4 @@
-using Microsoft.ML.Trainers.LightGbm;
-using static Microsoft.ML.Trainers.LightGbm.Options;
+using Microsoft.ML.Trainers.LightGbm;
 
 namespace Microsoft.ML.Samples.Dynamic.Trainers.BinaryClassification
 {
@@ -19,7 +18,7 @@ public static void Example()
 
             // Create the pipeline with LightGbm Estimator using advanced options.
             var pipeline = mlContext.BinaryClassification.Trainers.LightGbm(
-                                new Options
+                                new LightGbmBinaryTrainer.Options
                                 {
                                     Booster = new GossBooster.Options
                                     {

docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/MulticlassClassification/LightGbmWithOptions.cs

@@ -3,7 +3,6 @@
 using Microsoft.ML.Data;
 using Microsoft.ML.SamplesUtils;
 using Microsoft.ML.Trainers.LightGbm;
-using static Microsoft.ML.Trainers.LightGbm.Options;
 
 namespace Microsoft.ML.Samples.Dynamic.Trainers.MulticlassClassification
 {
@@ -33,11 +32,11 @@ public static void Example()
             //  - Convert the string labels into key types.
             //  - Apply LightGbm multiclass trainer with advanced options.
             var pipeline = mlContext.Transforms.Conversion.MapValueToKey("LabelIndex", "Label")
-                        .Append(mlContext.MulticlassClassification.Trainers.LightGbm(new Options
+                        .Append(mlContext.MulticlassClassification.Trainers.LightGbm(new LightGbmMulticlassTrainer.Options
                         {
                             LabelColumnName = "LabelIndex",
                             FeatureColumnName = "Features",
-                            Booster = new DartBooster.Options
+                            Booster = new DartBooster.Options()
                             {
                                 TreeDropFraction = 0.15,
                                 XgboostDartMode = false

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

@@ -1,5 +1,4 @@
 using Microsoft.ML.Trainers.LightGbm;
-using static Microsoft.ML.Trainers.LightGbm.Options;
 
 namespace Microsoft.ML.Samples.Dynamic.Trainers.Ranking
 {
@@ -21,13 +20,13 @@ public static void Example()
 
             // 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
+                new LightGbmRankingTrainer.Options
                 {
                     NumberOfLeaves = 4,
                     MinimumExampleCountPerGroup = 10,
                     LearningRate = 0.1,
                     NumberOfIterations = 2,
-                    Booster = new TreeBooster.Options
+                    Booster = new GradientBooster.Options
                     {
                         FeatureFraction = 0.9
                     }

docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/Regression/LightGbmWithOptions.cs

@@ -2,7 +2,6 @@
 using System.Linq;
 using Microsoft.ML.Data;
 using Microsoft.ML.Trainers.LightGbm;
-using static Microsoft.ML.Trainers.LightGbm.Options;
 
 namespace Microsoft.ML.Samples.Dynamic.Trainers.Regression
 {
@@ -36,13 +35,13 @@ public static void Example()
                 .Where(name => name != labelName) // Drop the Label
                 .ToArray();
             var pipeline = mlContext.Transforms.Concatenate("Features", featureNames)
-                           .Append(mlContext.Regression.Trainers.LightGbm(new Options
+                           .Append(mlContext.Regression.Trainers.LightGbm(new LightGbmRegressionTrainer.Options
                            {
                                LabelColumnName = labelName,
                                NumberOfLeaves = 4,
                                MinimumExampleCountPerLeaf = 6,
                                LearningRate = 0.001,
-                               Booster = new GossBooster.Options
+                               Booster = new GossBooster.Options()
                                {
                                    TopRate = 0.3,
                                    OtherRate = 0.2

src/Microsoft.ML.LightGbm.StaticPipe/LightGbmStaticExtensions.cs

@@ -42,7 +42,7 @@ public static Scalar<float> LightGbm(this RegressionCatalog.RegressionTrainers c
             int? numberOfLeaves = null,
             int? minimumExampleCountPerLeaf = null,
             double? learningRate = null,
-            int numberOfIterations = Options.Defaults.NumberOfIterations,
+            int numberOfIterations = Defaults.NumberOfIterations,
             Action<LightGbmRegressionModelParameters> onFit = null)
         {
             CheckUserValues(label, features, weights, numberOfLeaves, minimumExampleCountPerLeaf, learningRate, numberOfIterations, onFit);
@@ -76,10 +76,11 @@ public static Scalar<float> LightGbm(this RegressionCatalog.RegressionTrainers c
         /// <returns>The Score output column indicating the predicted value.</returns>
         public static Scalar<float> LightGbm(this RegressionCatalog.RegressionTrainers catalog,
             Scalar<float> label, Vector<float> features, Scalar<float> weights,
-            Options options,
+            LightGbmRegressionTrainer.Options options,
             Action<LightGbmRegressionModelParameters> onFit = null)
         {
-            CheckUserValues(label, features, weights, options, onFit);
+            Contracts.CheckValue(options, nameof(options));
+            CheckUserValues(label, features, weights, onFit);
 
             var rec = new TrainerEstimatorReconciler.Regression(
                (env, labelName, featuresName, weightsName) =>
@@ -128,7 +129,7 @@ public static (Scalar<float> score, Scalar<float> probability, Scalar<bool> pred
             int? numberOfLeaves = null,
             int? minimumExampleCountPerLeaf = null,
             double? learningRate = null,
-            int numberOfIterations = Options.Defaults.NumberOfIterations,
+            int numberOfIterations = Defaults.NumberOfIterations,
             Action<CalibratedModelParametersBase<LightGbmBinaryModelParameters, PlattCalibrator>> onFit = null)
         {
             CheckUserValues(label, features, weights, numberOfLeaves, minimumExampleCountPerLeaf, learningRate, numberOfIterations, onFit);
@@ -165,10 +166,11 @@ public static (Scalar<float> score, Scalar<float> probability, Scalar<bool> pred
         /// from negative to positive infinity), the calibrated prediction (from 0 to 1), and the predicted label.</returns>
         public static (Scalar<float> score, Scalar<float> probability, Scalar<bool> predictedLabel) LightGbm(this BinaryClassificationCatalog.BinaryClassificationTrainers catalog,
             Scalar<bool> label, Vector<float> features, Scalar<float> weights,
-            Options options,
+            LightGbmBinaryTrainer.Options options,
             Action<CalibratedModelParametersBase<LightGbmBinaryModelParameters, PlattCalibrator>> onFit = null)
         {
-            CheckUserValues(label, features, weights, options, onFit);
+            Contracts.CheckValue(options, nameof(options));
+            CheckUserValues(label, features, weights, onFit);
 
             var rec = new TrainerEstimatorReconciler.BinaryClassifier(
                (env, labelName, featuresName, weightsName) =>
@@ -215,7 +217,7 @@ public static Scalar<float> LightGbm<TVal>(this RankingCatalog.RankingTrainers c
             int? numberOfLeaves = null,
             int? minimumExampleCountPerLeaf = null,
             double? learningRate = null,
-            int numberOfIterations = Options.Defaults.NumberOfIterations,
+            int numberOfIterations = Defaults.NumberOfIterations,
             Action<LightGbmRankingModelParameters> onFit = null)
         {
             CheckUserValues(label, features, weights, numberOfLeaves, minimumExampleCountPerLeaf, learningRate, numberOfIterations, onFit);
@@ -253,10 +255,11 @@ public static Scalar<float> LightGbm<TVal>(this RankingCatalog.RankingTrainers c
         /// from negative to positive infinity), the calibrated prediction (from 0 to 1), and the predicted label.</returns>
         public static Scalar<float> LightGbm<TVal>(this RankingCatalog.RankingTrainers catalog,
            Scalar<float> label, Vector<float> features, Key<uint, TVal> groupId, Scalar<float> weights,
-            Options options,
+            LightGbmRankingTrainer.Options options,
             Action<LightGbmRankingModelParameters> onFit = null)
         {
-            CheckUserValues(label, features, weights, options, onFit);
+            Contracts.CheckValue(options, nameof(options));
+            CheckUserValues(label, features, weights, onFit);
             Contracts.CheckValue(groupId, nameof(groupId));
 
             var rec = new TrainerEstimatorReconciler.Ranker<TVal>(
@@ -309,7 +312,7 @@ public static (Vector<float> score, Key<uint, TVal> predictedLabel)
             int? numberOfLeaves = null,
             int? minimumExampleCountPerLeaf = null,
             double? learningRate = null,
-            int numberOfIterations = Options.Defaults.NumberOfIterations,
+            int numberOfIterations = Defaults.NumberOfIterations,
             Action<OneVersusAllModelParameters> onFit = null)
         {
             CheckUserValues(label, features, weights, numberOfLeaves, minimumExampleCountPerLeaf, learningRate, numberOfIterations, onFit);
@@ -347,10 +350,11 @@ public static (Vector<float> score, Key<uint, TVal> predictedLabel)
             Key<uint, TVal> label,
             Vector<float> features,
             Scalar<float> weights,
-            Options options,
+            LightGbmMulticlassTrainer.Options options,
             Action<OneVersusAllModelParameters> onFit = null)
         {
-            CheckUserValues(label, features, weights, options, onFit);
+            Contracts.CheckValue(options, nameof(options));
+            CheckUserValues(label, features, weights, onFit);
 
             var rec = new TrainerEstimatorReconciler.MulticlassClassificationReconciler<TVal>(
                 (env, labelName, featuresName, weightsName) =>
@@ -386,14 +390,11 @@ private static void CheckUserValues(PipelineColumn label, Vector<float> features
             Contracts.CheckValueOrNull(onFit);
         }
 
-        private static void CheckUserValues(PipelineColumn label, Vector<float> features, Scalar<float> weights,
-            Options options,
-            Delegate onFit)
+        private static void CheckUserValues(PipelineColumn label, Vector<float> features, Scalar<float> weights, Delegate onFit)
         {
             Contracts.CheckValue(label, nameof(label));
             Contracts.CheckValue(features, nameof(features));
             Contracts.CheckValueOrNull(weights);
-            Contracts.CheckValue(options, nameof(options));
             Contracts.CheckValueOrNull(onFit);
         }
     }