Skip to content

Cleaned LightGBM documentation #2886

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Mar 11, 2019
Merged

Cleaned LightGBM documentation #2886

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
91a8d21
LightGBM API, trainers, boosters, and options documentation.
Mar 5, 2019
44d7022
Addressed PR comments and fixed test.
Mar 8, 2019
6f6c255
Addressed PR comments.
Mar 11, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
220 changes: 213 additions & 7 deletions src/Microsoft.ML.LightGBM/LightGbmArguments.cs
View file
Open in desktop

Large diffs are not rendered by default.

11 changes: 4 additions & 7 deletions src/Microsoft.ML.LightGBM/LightGbmBinaryTrainer.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,13 +79,10 @@ private static IPredictorProducing<float> Create(IHostEnvironment env, ModelLoad
}
}

///<summary>
/// Trains a Light GBM Model.
///</summary>
/// <remarks>
/// Light GBM is an open source implementation of boosted trees.
/// <a href = 'https://github.com/Microsoft/LightGBM/wiki' > GitHub: LightGBM</a>
/// </remarks>
/// <summary>
/// The <see cref="IEstimator{TTransformer}"/> for training a boosted decision tree binary classification model using LightGBM.
/// </summary>
/// <include file='doc.xml' path='doc/members/member[@name="LightGBM_remarks"]/*' />
public sealed class LightGbmBinaryTrainer : LightGbmTrainerBase<float,
BinaryPredictionTransformer<CalibratedModelParametersBase<LightGbmBinaryModelParameters, PlattCalibrator>>,
CalibratedModelParametersBase<LightGbmBinaryModelParameters, PlattCalibrator>>
Expand Down
74 changes: 44 additions & 30 deletions src/Microsoft.ML.LightGBM/LightGbmCatalog.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,20 +14,20 @@ namespace Microsoft.ML
public static class LightGbmExtensions
{
/// <summary>
/// Predict a target using a decision tree regression model trained with the <see cref="LightGbmRegressorTrainer"/>.
/// Predict a target using a gradient boosting decision tree regression model trained with the <see cref="LightGbmRegressorTrainer"/>.
/// </summary>
/// <param name="catalog">The <see cref="RegressionCatalog"/>.</param>
/// <param name="labelColumnName">The name of the label column.</param>
/// <param name="featureColumnName">The name of the feature column.</param>
/// <param name="exampleWeightColumnName">The name of the example weight column (optional).</param>
/// <param name="numberOfLeaves">The number of leaves to use.</param>
/// <param name="minimumExampleCountPerLeaf">The minimal number of data points allowed in a leaf of the tree, out of the subsampled data.</param>
/// <param name="numberOfLeaves">The maximum number of leaves in one tree.</param>
/// <param name="minimumExampleCountPerLeaf">The minimal number of data points required to form a new tree leaf.</param>
/// <param name="learningRate">The learning rate.</param>
/// <param name="numberOfIterations">The number of iterations to use.</param>
/// <param name="numberOfIterations">The number of boosting iterations. A new tree is created in each iteration, so this is equivalent to the number of trees.</param>
/// <example>
/// <format type="text/markdown">
/// <![CDATA[
/// [!code-csharp[ScoreTensorFlowModel](~/../docs/samples/docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/Regression/LightGBMRegression.cs)]
/// [!code-csharp[LightGbmRegression](~/../docs/samples/docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/Regression/LightGbm.cs)]
/// ]]>
/// </format>
/// </example>
Expand All @@ -46,14 +46,14 @@ public static LightGbmRegressorTrainer LightGbm(this RegressionCatalog.Regressio
}

/// <summary>
/// Predict a target using a decision tree regression model trained with the <see cref="LightGbmRegressorTrainer"/>.
/// Predict a target using a gradient boosting decision tree regression model trained with the <see cref="LightGbmRegressorTrainer"/> and advanced options.
/// </summary>
/// <param name="catalog">The <see cref="RegressionCatalog"/>.</param>
/// <param name="options">Advanced options to the algorithm.</param>
/// <param name="options">Trainer options.</param>
Copy link
Member

@sfilipi sfilipi Mar 8, 2019 •
edited by shmoradims
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Trainer [](start = 34, length = 7)

either estimator or algorithm. I think the other catalogs use "Algorithm advanced options" #WontFix

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've been changing them to "Trainer Options" based on Rogan's comment on AveragedPercentron. I don't want to change back everything. Trainer sounds good enough, unless there's a strong objection.

In reply to: 263689283 [](ancestors = 263689283)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is preferred to "advanced".

In reply to: 263905459 [](ancestors = 263905459,263689283)

/// <example>
/// <format type="text/markdown">
/// <![CDATA[
/// [!code-csharp[ScoreTensorFlowModel](~/../docs/samples/docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/Regression/LightGBMRegressionWithOptions.cs)]
/// [!code-csharp[LightGbmRegression](~/../docs/samples/docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/Regression/LightGbmWithOptions.cs)]
/// ]]>
/// </format>
/// </example>
Expand All @@ -66,20 +66,20 @@ public static LightGbmRegressorTrainer LightGbm(this RegressionCatalog.Regressio
}

/// <summary>
/// Predict a target using a decision tree binary classification model trained with the <see cref="LightGbmBinaryTrainer"/>.
/// Predict a target using a gradient boosting decision tree binary classification model trained with the <see cref="LightGbmBinaryTrainer"/>.
/// </summary>
/// <param name="catalog">The <see cref="BinaryClassificationCatalog"/>.</param>
/// <param name="labelColumnName">The name of the label column.</param>
/// <param name="featureColumnName">The name of the feature column.</param>
/// <param name="exampleWeightColumnName">The name of the example weight column (optional).</param>
/// <param name="numberOfLeaves">The number of leaves to use.</param>
/// <param name="minimumExampleCountPerLeaf">The minimal number of data points allowed in a leaf of the tree, out of the subsampled data.</param>
/// <param name="numberOfLeaves">The maximum number of leaves in one tree.</param>
/// <param name="minimumExampleCountPerLeaf">The minimal number of data points required to form a new tree leaf.</param>
/// <param name="learningRate">The learning rate.</param>
/// <param name="numberOfIterations">The number of iterations to use.</param>
/// <param name="numberOfIterations">The number of boosting iterations. A new tree is created in each iteration, so this is equivalent to the number of trees.</param>
/// <example>
/// <format type="text/markdown">
/// <![CDATA[
/// [!code-csharp[ScoreTensorFlowModel](~/../docs/samples/docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/BinaryClassification/LightGbmBinaryClassification.cs)]
/// [!code-csharp[LightGbmBinaryClassification](~/../docs/samples/docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/BinaryClassification/LightGbm.cs)]
/// ]]>
/// </format>
/// </example>
Expand All @@ -98,14 +98,14 @@ public static LightGbmBinaryTrainer LightGbm(this BinaryClassificationCatalog.Bi
}

/// <summary>
/// Predict a target using a decision tree binary classification model trained with the <see cref="LightGbmBinaryTrainer"/>.
/// Predict a target using a gradient boosting decision tree binary classification model trained with the <see cref="LightGbmBinaryTrainer"/> and advanced options.
/// </summary>
/// <param name="catalog">The <see cref="BinaryClassificationCatalog"/>.</param>
/// <param name="options">Advanced options to the algorithm.</param>
/// <param name="options">Trainer options.</param>
/// <example>
/// <format type="text/markdown">
/// <![CDATA[
/// [!code-csharp[ScoreTensorFlowModel](~/../docs/samples/docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/BinaryClassification/LightGBMBinaryClassificationWithOptions.cs)]
/// [!code-csharp[LightGbmBinaryClassification](~/../docs/samples/docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/BinaryClassification/LightGbmWithOptions.cs)]
/// ]]>
/// </format>
/// </example>
Expand All @@ -118,17 +118,24 @@ public static LightGbmBinaryTrainer LightGbm(this BinaryClassificationCatalog.Bi
}

/// <summary>
/// Predict a target using a decision tree ranking model trained with the <see cref="LightGbmRankingTrainer"/>.
/// Predict a target using a gradient boosting decision tree ranking model trained with the <see cref="LightGbmRankingTrainer"/>.
/// </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="rowGroupColumnName">The name of the group column.</param>
/// <param name="exampleWeightColumnName">The name of the example weight column (optional).</param>
/// <param name="numberOfLeaves">The number of leaves to use.</param>
/// <param name="minimumExampleCountPerLeaf">The minimal number of data points allowed in a leaf of the tree, out of the subsampled data.</param>
/// <param name="numberOfLeaves">The maximum number of leaves in one tree.</param>
/// <param name="minimumExampleCountPerLeaf">The minimal number of data points required to form a new tree leaf.</param>
/// <param name="learningRate">The learning rate.</param>
/// <param name="numberOfIterations">The number of iterations to use.</param>
/// <param name="numberOfIterations">The number of boosting iterations. A new tree is created in each iteration, so this is equivalent to the number of trees.</param>
/// <example>
/// <format type="text/markdown">
/// <![CDATA[
/// [!code-csharp[LightGbmRanking](~/../docs/samples/docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/Ranking/LightGbm.cs)]
/// ]]>
/// </format>
/// </example>
public static LightGbmRankingTrainer LightGbm(this RankingCatalog.RankingTrainers catalog,
string labelColumnName = DefaultColumnNames.Label,
string featureColumnName = DefaultColumnNames.Features,
Expand All @@ -145,10 +152,17 @@ public static LightGbmRankingTrainer LightGbm(this RankingCatalog.RankingTrainer
}

/// <summary>
/// Predict a target using a decision tree ranking model trained with the <see cref="LightGbmRankingTrainer"/>.
/// Predict a target using a gradient boosting decision tree ranking model trained with the <see cref="LightGbmRankingTrainer"/> and advanced options.
/// </summary>
/// <param name="catalog">The <see cref="RankingCatalog"/>.</param>
/// <param name="options">Advanced options to the algorithm.</param>
/// <param name="options">Trainer options.</param>
/// <example>
/// <format type="text/markdown">
/// <![CDATA[
/// [!code-csharp[LightGbmRanking](~/../docs/samples/docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/Ranking/LightGbmWithOptions.cs)]
/// ]]>
/// </format>
/// </example>
public static LightGbmRankingTrainer LightGbm(this RankingCatalog.RankingTrainers catalog,
Options options)
{
Expand All @@ -158,20 +172,20 @@ public static LightGbmRankingTrainer LightGbm(this RankingCatalog.RankingTrainer
}

/// <summary>
/// Predict a target using a decision tree multiclass classification model trained with the <see cref="LightGbmMulticlassTrainer"/>.
/// Predict a target using a gradient boosting decision tree multiclass classification model trained with the <see cref="LightGbmMulticlassTrainer"/>.
/// </summary>
/// <param name="catalog">The <see cref="MulticlassClassificationCatalog"/>.</param>
/// <param name="labelColumnName">The name of the label column.</param>
/// <param name="featureColumnName">The name of the feature column.</param>
/// <param name="exampleWeightColumnName">The name of the example weight column (optional).</param>
/// <param name="numberOfLeaves">The number of leaves to use.</param>
/// <param name="minimumExampleCountPerLeaf">The minimal number of data points allowed in a leaf of the tree, out of the subsampled data.</param>
/// <param name="numberOfLeaves">The maximum number of leaves in one tree.</param>
/// <param name="minimumExampleCountPerLeaf">The minimal number of data points required to form a new tree leaf.</param>
/// <param name="learningRate">The learning rate.</param>
/// <param name="numberOfIterations">The number of iterations to use.</param>
/// <param name="numberOfIterations">The number of boosting iterations. A new tree is created in each iteration, so this is equivalent to the number of trees.</param>
/// <example>
/// <format type="text/markdown">
/// <![CDATA[
/// [!code-csharp[ScoreTensorFlowModel](~/../docs/samples/docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/MulticlassClassification/LightGBMMulticlassClassification.cs)]
/// [!code-csharp[LightGbmMulticlassClassification](~/../docs/samples/docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/MulticlassClassification/LightGbm.cs)]
/// ]]>
/// </format>
/// </example>
Expand All @@ -190,14 +204,14 @@ public static LightGbmMulticlassTrainer LightGbm(this MulticlassClassificationCa
}

/// <summary>
/// Predict a target using a decision tree multiclass classification model trained with the <see cref="LightGbmMulticlassTrainer"/>.
/// Predict a target using a gradient boosting decision tree multiclass classification model trained with the <see cref="LightGbmMulticlassTrainer"/> and advanced options.
/// </summary>
/// <param name="catalog">The <see cref="MulticlassClassificationCatalog"/>.</param>
/// <param name="options">Advanced options to the algorithm.</param>
/// <param name="options">Trainer options.</param>
/// <example>
/// <format type="text/markdown">
/// <![CDATA[
/// [!code-csharp[ScoreTensorFlowModel](~/../docs/samples/docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/MulticlassClassification/LightGBMMulticlassClassificationWithOptions.cs)]
/// [!code-csharp[LightGbmMulticlassClassification](~/../docs/samples/docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/MulticlassClassification/LightGbmWithOptions.cs)]
/// ]]>
/// </format>
/// </example>
Expand Down
4 changes: 4 additions & 0 deletions src/Microsoft.ML.LightGBM/LightGbmMulticlassTrainer.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,10 @@

namespace Microsoft.ML.LightGBM
{
/// <summary>
/// The <see cref="IEstimator{TTransformer}"/> for training a boosted decision tree multi-class classification model using LightGBM.
/// </summary>
/// <include file='doc.xml' path='doc/members/member[@name="LightGBM_remarks"]/*' />
public sealed class LightGbmMulticlassTrainer : LightGbmTrainerBase<VBuffer<float>, MulticlassPredictionTransformer<OneVersusAllModelParameters>, OneVersusAllModelParameters>
{
internal const string Summary = "LightGBM Multi Class Classifier";
Expand Down
4 changes: 4 additions & 0 deletions src/Microsoft.ML.LightGBM/LightGbmRankingTrainer.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,10 @@ 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"]/*' />
public sealed class LightGbmRankingTrainer : LightGbmTrainerBase<float, RankingPredictionTransformer<LightGbmRankingModelParameters>, LightGbmRankingModelParameters>
{
internal const string UserName = "LightGBM Ranking";
Expand Down
4 changes: 4 additions & 0 deletions src/Microsoft.ML.LightGBM/LightGbmRegressionTrainer.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,10 @@ private static LightGbmRegressionModelParameters Create(IHostEnvironment env, Mo
}
}

/// <summary>
/// The <see cref="IEstimator{TTransformer}"/> for training a boosted decision tree regression model using LightGBM.
/// </summary>
/// <include file='doc.xml' path='doc/members/member[@name="LightGBM_remarks"]/*' />
public sealed class LightGbmRegressorTrainer : LightGbmTrainerBase<float, RegressionPredictionTransformer<LightGbmRegressionModelParameters>, LightGbmRegressionModelParameters>
{
internal const string Summary = "LightGBM Regression";
Expand Down
16 changes: 16 additions & 0 deletions src/Microsoft.ML.LightGBM/doc.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
<?xml version="1.0" encoding="utf-8"?>
<doc>
<members>
<!--
The following text describes the LightGbm algorithm details.
It's used for the remarks section of all LightGbm-based trainers (binary, multiclass, regression, ranking)
-->
<member name="LightGBM_remarks">
<remarks>
LightGBM is an open source implementation of gradient boosting decision tree. For implementation details, please see
<a href='https://lightgbm.readthedocs.io/en/latest/index.html'>LightGBM's official documentation</a> or
<a href='https://papers.nips.cc/paper/6907-lightgbm-a-highly-efficient-gradient-boosting-decision-tree.pdf'>this paper</a>.
</remarks>
</member>
</members>
</doc>
20 changes: 10 additions & 10 deletions test/BaselineOutput/Common/EntryPoints/core_manifest.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11360,7 +11360,7 @@
{
"Name": "CustomGains",
"Type": "String",
"Desc": "Comma seperated list of gains associated to each relevance label.",
"Desc": "Comma separated list of gains associated to each relevance label.",
Copy link
Contributor

@rogancarr rogancarr Mar 8, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

separated [](start = 25, length = 9)

Nice #Resolved

"Aliases": [
"gains"
],
Expand Down Expand Up @@ -11478,7 +11478,7 @@
{
"Name": "CategoricalSmoothing",
"Type": "Float",
"Desc": "Lapalace smooth term in categorical feature spilt. Avoid the bias of small categories.",
"Desc": "Laplace smooth term in categorical feature split. Avoid the bias of small categories.",
"Required": false,
"SortOrder": 150.0,
"IsNullable": false,
Expand Down Expand Up @@ -11863,7 +11863,7 @@
{
"Name": "CustomGains",
"Type": "String",
"Desc": "Comma seperated list of gains associated to each relevance label.",
"Desc": "Comma separated list of gains associated to each relevance label.",
"Aliases": [
"gains"
],
Expand Down Expand Up @@ -11981,7 +11981,7 @@
{
"Name": "CategoricalSmoothing",
"Type": "Float",
"Desc": "Lapalace smooth term in categorical feature spilt. Avoid the bias of small categories.",
"Desc": "Laplace smooth term in categorical feature split. Avoid the bias of small categories.",
"Required": false,
"SortOrder": 150.0,
"IsNullable": false,
Expand Down Expand Up @@ -12366,7 +12366,7 @@
{
"Name": "CustomGains",
"Type": "String",
"Desc": "Comma seperated list of gains associated to each relevance label.",
"Desc": "Comma separated list of gains associated to each relevance label.",
"Aliases": [
"gains"
],
Expand Down Expand Up @@ -12484,7 +12484,7 @@
{
"Name": "CategoricalSmoothing",
"Type": "Float",
"Desc": "Lapalace smooth term in categorical feature spilt. Avoid the bias of small categories.",
"Desc": "Laplace smooth term in categorical feature split. Avoid the bias of small categories.",
"Required": false,
"SortOrder": 150.0,
"IsNullable": false,
Expand Down Expand Up @@ -12869,7 +12869,7 @@
{
"Name": "CustomGains",
"Type": "String",
"Desc": "Comma seperated list of gains associated to each relevance label.",
"Desc": "Comma separated list of gains associated to each relevance label.",
"Aliases": [
"gains"
],
Expand Down Expand Up @@ -12987,7 +12987,7 @@
{
"Name": "CategoricalSmoothing",
"Type": "Float",
"Desc": "Lapalace smooth term in categorical feature spilt. Avoid the bias of small categories.",
"Desc": "Laplace smooth term in categorical feature split. Avoid the bias of small categories.",
"Required": false,
"SortOrder": 150.0,
"IsNullable": false,
Expand Down Expand Up @@ -23511,13 +23511,13 @@
"Components": [
{
"Name": "dart",
"Desc": "Dropouts meet Multiple Additive Regresion Trees. See https://arxiv.org/abs/1505.01866",
"Desc": "Dropouts meet Multiple Additive Regression Trees. See https://arxiv.org/abs/1505.01866",
"FriendlyName": "Tree Dropout Tree Booster",
"Settings": [
{
"Name": "TreeDropFraction",
"Type": "Float",
"Desc": "The drop ratio for trees. Range:(0,1).",
"Desc": "The drop ratio for trees. Range:[0,1].",
"Required": false,
"SortOrder": 150.0,
"IsNullable": false,
Expand Down