XML documentation for LightGBM Ranking trainer.

docs/api-reference/algo-details-lightgbm.md

@@ -0,0 +1,5 @@
+### Training Algorithm Details
+LightGBM is an open source implementation of gradient boosting decision tree.
+For implementation details, please see [LightGBM's official
+documentation](https://lightgbm.readthedocs.io/en/latest/index.html) or this
+[paper](https://papers.nips.cc/paper/6907-lightgbm-a-highly-efficient-gradient-boosting-decision-tree.pdf).

src/Microsoft.ML.FastTree/FastTreeClassification.cs

@@ -119,8 +119,8 @@ private static IPredictorProducing<float> Create(IHostEnvironment env, ModelLoad
     /// ]]>
     /// </format>
     /// </remarks>
-    /// <seealso cref="Microsoft.ML.TreeExtensions.FastTree(Microsoft.ML.BinaryClassificationCatalog.BinaryClassificationTrainers,System.String,System.String,System.String,System.Int32,System.Int32,System.Int32,System.Double)"/>
-    /// <seealso cref="Microsoft.ML.TreeExtensions.FastTree(Microsoft.ML.BinaryClassificationCatalog.BinaryClassificationTrainers,Microsoft.ML.Trainers.FastTree.FastTreeBinaryTrainer.Options)"/>
+    /// <seealso cref="TreeExtensions.FastTree(BinaryClassificationCatalog.BinaryClassificationTrainers, string, string, string, int, int, int, double)"/>
+    /// <seealso cref="TreeExtensions.FastTree(BinaryClassificationCatalog.BinaryClassificationTrainers, FastTreeBinaryTrainer.Options)"/>
     /// <seealso cref="Options"/>
     public sealed partial class FastTreeBinaryTrainer :
         BoostingFastTreeTrainerBase<FastTreeBinaryTrainer.Options,

src/Microsoft.ML.FastTree/FastTreeRegression.cs

@@ -51,8 +51,8 @@ namespace Microsoft.ML.Trainers.FastTree
     /// ]]>
     /// </format>
     /// </remarks>
-    /// <seealso cref="Microsoft.ML.TreeExtensions.FastTree(Microsoft.ML.RegressionCatalog.RegressionTrainers,System.String,System.String,System.String,System.Int32,System.Int32,System.Int32,System.Double)"/>
-    /// <seealso cref="Microsoft.ML.TreeExtensions.FastTree(Microsoft.ML.RegressionCatalog.RegressionTrainers,Microsoft.ML.Trainers.FastTree.FastTreeRegressionTrainer.Options)"/>
+    /// <seealso cref="TreeExtensions.FastTree(RegressionCatalog.RegressionTrainers, string, string, string, int, int, int, double)"/>
+    /// <seealso cref="TreeExtensions.FastTree(RegressionCatalog.RegressionTrainers, FastTreeRegressionTrainer.Options)"/>
     /// <seealso cref="Options"/>
     public sealed partial class FastTreeRegressionTrainer
         : BoostingFastTreeTrainerBase<FastTreeRegressionTrainer.Options, RegressionPredictionTransformer<FastTreeRegressionModelParameters>, FastTreeRegressionModelParameters>

src/Microsoft.ML.FastTree/RandomForestClassification.cs

@@ -132,8 +132,8 @@ private static IPredictorProducing<float> Create(IHostEnvironment env, ModelLoad
     /// ]]>
     /// </format>
     /// </remarks>
-    /// <seealso cref="Microsoft.ML.TreeExtensions.FastForest(Microsoft.ML.BinaryClassificationCatalog.BinaryClassificationTrainers,System.String,System.String,System.String,System.Int32,System.Int32,System.Int32)"/>
-    /// <seealso cref="Microsoft.ML.TreeExtensions.FastForest(Microsoft.ML.BinaryClassificationCatalog.BinaryClassificationTrainers,Microsoft.ML.Trainers.FastTree.FastForestBinaryTrainer.Options)"/>
+    /// <seealso cref="TreeExtensions.FastForest(BinaryClassificationCatalog.BinaryClassificationTrainers, string, string, string, int, int, int)"/>
+    /// <seealso cref="TreeExtensions.FastForest(BinaryClassificationCatalog.BinaryClassificationTrainers, FastForestBinaryTrainer.Options)"/>
     /// <seealso cref="Options"/>
     public sealed partial class FastForestBinaryTrainer :
         RandomForestTrainerBase<FastForestBinaryTrainer.Options, BinaryPredictionTransformer<FastForestBinaryModelParameters>, FastForestBinaryModelParameters>

src/Microsoft.ML.FastTree/RandomForestRegression.cs

@@ -263,8 +263,8 @@ ISchemaBindableMapper IQuantileRegressionPredictor.CreateMapper(Double[] quantil
     /// ]]>
     /// </format>
     /// </remarks>
-    /// <seealso cref="Microsoft.ML.TreeExtensions.FastForest(Microsoft.ML.RegressionCatalog.RegressionTrainers,System.String,System.String,System.String,System.Int32,System.Int32,System.Int32)"/>
-    /// <seealso cref="Microsoft.ML.TreeExtensions.FastForest(Microsoft.ML.RegressionCatalog.RegressionTrainers,Microsoft.ML.Trainers.FastTree.FastForestRegressionTrainer.Options)"/>
+    /// <seealso cref="TreeExtensions.FastForest(RegressionCatalog.RegressionTrainers, string, string, string, int, int, int)"/>
+    /// <seealso cref="TreeExtensions.FastForest(RegressionCatalog.RegressionTrainers, FastForestRegressionTrainer.Options)"/>
     /// <seealso cref="Options"/>
     public sealed partial class FastForestRegressionTrainer
         : RandomForestTrainerBase<FastForestRegressionTrainer.Options, RegressionPredictionTransformer<FastForestRegressionModelParameters>, FastForestRegressionModelParameters>

src/Microsoft.ML.LightGbm/LightGbmCatalog.cs

@@ -118,11 +118,11 @@ public static LightGbmBinaryTrainer LightGbm(this BinaryClassificationCatalog.Bi
         }
 
         /// <summary>
-        /// Predict a target using a gradient boosting decision tree ranking model trained with the <see cref="LightGbmRankingTrainer"/>.
+        /// Create <see cref="LightGbmRankingTrainer"/>, which predict a target using a gradient boosting decision tree ranking model.
         /// </summary>
         /// <param name="catalog">The <see cref="RankingCatalog"/>.</param>
-        /// <param name="labelColumnName">The name of the label column.</param>
-        /// <param name="featureColumnName">The name of the feature column.</param>
+        /// <param name="labelColumnName">The name of the label column. The column data must be <see cref="System.Single"/>.</param>
+        /// <param name="featureColumnName">The name of the feature column. The column data must be a known-sized vector of <see cref="System.Single"/>.</param>
         /// <param name="rowGroupColumnName">The name of the group column.</param>
         /// <param name="exampleWeightColumnName">The name of the example weight column (optional).</param>
         /// <param name="numberOfLeaves">The maximum number of leaves in one tree.</param>
@@ -153,7 +153,7 @@ public static LightGbmRankingTrainer LightGbm(this RankingCatalog.RankingTrainer
         }
 
         /// <summary>
-        /// Predict a target using a gradient boosting decision tree ranking model trained with the <see cref="LightGbmRankingTrainer"/> and advanced options.
+        /// Create <see cref="LightGbmRankingTrainer"/> with advanced options, which predict a target using a gradient boosting decision tree ranking model.
         /// </summary>
         /// <param name="catalog">The <see cref="RankingCatalog"/>.</param>
         /// <param name="options">Trainer options.</param>

src/Microsoft.ML.LightGbm/LightGbmRankingTrainer.cs

@@ -73,7 +73,28 @@ private static LightGbmRankingModelParameters Create(IHostEnvironment env, Model
     /// <summary>
     /// The <see cref="IEstimator{TTransformer}"/> for training a boosted decision tree ranking model using LightGBM.
     /// </summary>
-    /// <include file='doc.xml' path='doc/members/member[@name="LightGBM_remarks"]/*' />
+    /// <remarks>
+    /// <format type="text/markdown"><![CDATA[
+    /// To create this trainer, use [LightGbm](xref:Microsoft.ML.LightGbmExtensions.LightGbm(Microsoft.ML.RankingCatalog.RankingTrainers,System.String,System.String,System.String,System.String,System.Nullable{System.Int32},System.Nullable{System.Int32},System.Nullable{System.Double},System.Int32))
+    /// or [LightGbm(Options)](xref:Microsoft.ML.LightGbmExtensions.LightGbm(Microsoft.ML.RankingCatalog.RankingTrainers,Microsoft.ML.Trainers.LightGbm.LightGbmRankingTrainer.Options)).
+    ///
+    /// [!include[io](~/../docs/samples/docs/api-reference/io-columns-ranking.md)]
+    ///
+    /// ### Trainer Characteristics
+    /// |  |  |
+    /// | -- | -- |
+    /// | Machine learning task | Ranking |
+    /// | Is normalization required? | No |
+    /// | Is caching required? | No |
+    /// | Required NuGet in addition to Microsoft.ML | Microsoft.ML.FastTree |
+    ///
+    /// [!include[algorithm](~/../docs/samples/docs/api-reference/algo-details-lightgbm.md)]
+    /// ]]>
+    /// </format>
+    /// </remarks>
+    /// <seealso cref="LightGbmExtensions.LightGbm(RankingCatalog.RankingTrainers, string, string, string, string, int?, int?, double?, int)"/>
+    /// <seealso cref="LightGbmExtensions.LightGbm(RankingCatalog.RankingTrainers, LightGbmRankingTrainer.Options)"/>
+    /// <seealso cref="Options"/>
     public sealed class LightGbmRankingTrainer : LightGbmTrainerBase<LightGbmRankingTrainer.Options,
                                                                         float,
                                                                         RankingPredictionTransformer<LightGbmRankingModelParameters>,
@@ -85,6 +106,10 @@ public sealed class LightGbmRankingTrainer : LightGbmTrainerBase<LightGbmRanking
 
         private protected override PredictionKind PredictionKind => PredictionKind.Ranking;
 
+        /// <summary>
+        /// Options for the <see cref="LightGbmRankingTrainer"/> as used in
+        /// [LightGbm(Options)](xref:Microsoft.ML.LightGbmExtensions.LightGbm(Microsoft.ML.RankingCatalog.RankingTrainers,Microsoft.ML.Trainers.LightGbm.LightGbmRankingTrainer.Options)).
+        /// </summary>
         public sealed class Options : OptionsBase
         {
             public enum EvaluateMetricType
@@ -100,7 +125,7 @@ public enum EvaluateMetricType
             /// </summary>
             [Argument(ArgumentType.AtMostOnce, HelpText = "An array of gains associated to each relevance label.", ShortName = "gains")]
             [TGUI(Label = "Ranking Label Gain")]
-            public int[] CustomGains = { 0,3,7,15,31,63,127,255,511,1023,2047,4095 };
+            public int[] CustomGains = { 0, 3, 7, 15, 31, 63, 127, 255, 511, 1023, 2047, 4095 };
 
             /// <summary>
             /// Parameter for the sigmoid function.
@@ -130,8 +155,8 @@ internal override Dictionary<string, object> ToDictionary(IHost host)
             {
                 var res = base.ToDictionary(host);
                 res[GetOptionName(nameof(Sigmoid))] = Sigmoid;
-                res[GetOptionName(nameof(CustomGains))] = string.Join(",",CustomGains);
-                if(EvaluationMetric != EvaluateMetricType.Default)
+                res[GetOptionName(nameof(CustomGains))] = string.Join(",", CustomGains);
+                if (EvaluationMetric != EvaluateMetricType.Default)
                     res[GetOptionName(nameof(EvaluateMetricType))] = GetOptionName(EvaluationMetric.ToString());
 
                 return res;
@@ -168,14 +193,14 @@ internal LightGbmRankingTrainer(IHostEnvironment env,
             : this(env,
                   new Options()
                   {
-                    LabelColumnName = labelColumnName,
-                    FeatureColumnName = featureColumnName,
-                    ExampleWeightColumnName = weightsColumnName,
-                    RowGroupColumnName = rowGroupdColumnName,
-                    NumberOfLeaves = numberOfLeaves,
-                    MinimumExampleCountPerLeaf = minimumExampleCountPerLeaf,
-                    LearningRate = learningRate,
-                    NumberOfIterations = numberOfIterations
+                      LabelColumnName = labelColumnName,
+                      FeatureColumnName = featureColumnName,
+                      ExampleWeightColumnName = weightsColumnName,
+                      RowGroupColumnName = rowGroupdColumnName,
+                      NumberOfLeaves = numberOfLeaves,
+                      MinimumExampleCountPerLeaf = minimumExampleCountPerLeaf,
+                      LearningRate = learningRate,
+                      NumberOfIterations = numberOfIterations
                   })
         {
             Host.CheckNonEmpty(rowGroupdColumnName, nameof(rowGroupdColumnName));