diff --git a/src/Microsoft.ML.Core/EntryPoints/ModuleArgs.cs b/src/Microsoft.ML.Core/EntryPoints/ModuleArgs.cs index 2c4f877c1b..f991df73f0 100644 --- a/src/Microsoft.ML.Core/EntryPoints/ModuleArgs.cs +++ b/src/Microsoft.ML.Core/EntryPoints/ModuleArgs.cs @@ -529,9 +529,9 @@ public sealed class EntryPointAttribute : Attribute public string ShortName { get; set; } /// - /// Remarks on the Entry Point, for more extensive XML documentation on the C#API + /// The path to the XML documentation on the CSharpAPI component /// - public string Remarks { get; set; } + public string[] XmlInclude { get; set; } } /// diff --git a/src/Microsoft.ML.Core/EntryPoints/ModuleCatalog.cs b/src/Microsoft.ML.Core/EntryPoints/ModuleCatalog.cs index af45202937..93db75c169 100644 --- a/src/Microsoft.ML.Core/EntryPoints/ModuleCatalog.cs +++ b/src/Microsoft.ML.Core/EntryPoints/ModuleCatalog.cs @@ -44,7 +44,7 @@ public sealed class EntryPointInfo public readonly string Description; public readonly string ShortName; public readonly string FriendlyName; - public readonly string Remarks; + public readonly string[] XmlInclude; public readonly MethodInfo Method; public readonly Type InputType; public readonly Type OutputType; @@ -64,7 +64,7 @@ internal EntryPointInfo(IExceptionContext ectx, MethodInfo method, Method = method; ShortName = attribute.ShortName; FriendlyName = attribute.UserName; - Remarks = attribute.Remarks; + XmlInclude = attribute.XmlInclude; ObsoleteAttribute = obsoleteAttribute; // There are supposed to be 2 parameters, env and input for non-macro nodes. diff --git a/src/Microsoft.ML.FastTree/FastTree.cs b/src/Microsoft.ML.FastTree/FastTree.cs index 22a4e145b8..e7432139c5 100644 --- a/src/Microsoft.ML.FastTree/FastTree.cs +++ b/src/Microsoft.ML.FastTree/FastTree.cs @@ -82,31 +82,6 @@ public abstract class FastTreeTrainerBase : protected string InnerArgs => CmdParser.GetSettings(Host, Args, new TArgs()); - internal const string Remarks = @" -FastTrees is an efficient implementation of the MART gradient boosting algorithm. -Gradient boosting is a machine learning technique for regression problems. -It builds each regression tree in a step-wise fashion, using a predefined loss function to measure the error for each step and corrects for it in the next. -So this prediction model is actually an ensemble of weaker prediction models. In regression problems, boosting builds a series of of such trees in a step-wise fashion and then selects the optimal tree using an arbitrary differentiable loss function. - - -MART learns an ensemble of regression trees, which is a decision tree with scalar values in its leaves. -A decision (or regression) tree is a binary tree-like flow chart, where at each interior node one decides which of the two child nodes to continue to based on one of the feature values from the input. -At each leaf node, a value is returned. In the interior nodes, the decision is based on the test 'x <= v' where x is the value of the feature in the input sample and v is one of the possible values of this feature. -The functions that can be produced by a regression tree are all the piece-wise constant functions. - - -The ensemble of trees is produced by computing, in each step, a regression tree that approximates the gradient of the loss function, and adding it to the previous tree with coefficients that minimize the loss of the new tree. -The output of the ensemble produced by MART on a given instance is the sum of the tree outputs. - - -In case of a binary classification problem, the output is converted to a probability by using some form of calibration. -In case of a regression problem, the output is the predicted value of the function. -In case of a ranking problem, the instances are ordered by the output value of the ensemble. - -Wikipedia: Gradient boosting (Gradient tree boosting). -Greedy function approximation: A gradient boosting machine.. -"; - public override bool NeedNormalization => false; public override bool WantCaching => false; diff --git a/src/Microsoft.ML.FastTree/FastTreeArguments.cs b/src/Microsoft.ML.FastTree/FastTreeArguments.cs index 7262659e43..e6274e3155 100644 --- a/src/Microsoft.ML.FastTree/FastTreeArguments.cs +++ b/src/Microsoft.ML.FastTree/FastTreeArguments.cs @@ -20,6 +20,7 @@ public interface IFastTreeTrainerFactory : IComponentFactory { } + /// public sealed partial class FastTreeBinaryClassificationTrainer { [TlcModule.Component(Name = LoadNameValue, FriendlyName = UserNameValue, Desc = Summary)] diff --git a/src/Microsoft.ML.FastTree/FastTreeClassification.cs b/src/Microsoft.ML.FastTree/FastTreeClassification.cs index f694236166..18f61e6dbe 100644 --- a/src/Microsoft.ML.FastTree/FastTreeClassification.cs +++ b/src/Microsoft.ML.FastTree/FastTreeClassification.cs @@ -100,6 +100,7 @@ public static IPredictorProducing Create(IHostEnvironment env, ModelLoadC public override PredictionKind PredictionKind { get { return PredictionKind.BinaryClassification; } } } + /// public sealed partial class FastTreeBinaryClassificationTrainer : BoostingFastTreeTrainerBase> { @@ -336,13 +337,16 @@ public void AdjustTreeOutputs(IChannel ch, RegressionTree tree, } } + /// + /// The Entry Point for the FastTree Binary Classifier. + /// public static partial class FastTree { [TlcModule.EntryPoint(Name = "Trainers.FastTreeBinaryClassifier", Desc = FastTreeBinaryClassificationTrainer.Summary, - Remarks = FastTreeBinaryClassificationTrainer.Remarks, UserName = FastTreeBinaryClassificationTrainer.UserNameValue, - ShortName = FastTreeBinaryClassificationTrainer.ShortName)] + ShortName = FastTreeBinaryClassificationTrainer.ShortName, + XmlInclude = new[] { @"" })] public static CommonOutputs.BinaryClassificationOutput TrainBinary(IHostEnvironment env, FastTreeBinaryClassificationTrainer.Arguments input) { Contracts.CheckValue(env, nameof(env)); diff --git a/src/Microsoft.ML.FastTree/FastTreeRanking.cs b/src/Microsoft.ML.FastTree/FastTreeRanking.cs index 70919fbdea..6eabca8c78 100644 --- a/src/Microsoft.ML.FastTree/FastTreeRanking.cs +++ b/src/Microsoft.ML.FastTree/FastTreeRanking.cs @@ -38,6 +38,7 @@ namespace Microsoft.ML.Runtime.FastTree { + /// public sealed partial class FastTreeRankingTrainer : BoostingFastTreeTrainerBase, IHasLabelGains { @@ -1098,9 +1099,9 @@ public static partial class FastTree { [TlcModule.EntryPoint(Name = "Trainers.FastTreeRanker", Desc = FastTreeRankingTrainer.Summary, - Remarks = FastTreeRankingTrainer.Remarks, UserName = FastTreeRankingTrainer.UserNameValue, - ShortName = FastTreeRankingTrainer.ShortName)] + ShortName = FastTreeRankingTrainer.ShortName, + XmlInclude = new[] { @"" })] public static CommonOutputs.RankingOutput TrainRanking(IHostEnvironment env, FastTreeRankingTrainer.Arguments input) { Contracts.CheckValue(env, nameof(env)); diff --git a/src/Microsoft.ML.FastTree/FastTreeRegression.cs b/src/Microsoft.ML.FastTree/FastTreeRegression.cs index 9c50fe75fe..308437440a 100644 --- a/src/Microsoft.ML.FastTree/FastTreeRegression.cs +++ b/src/Microsoft.ML.FastTree/FastTreeRegression.cs @@ -31,6 +31,7 @@ namespace Microsoft.ML.Runtime.FastTree { + /// public sealed partial class FastTreeRegressionTrainer : BoostingFastTreeTrainerBase { public const string LoadNameValue = "FastTreeRegression"; @@ -450,9 +451,9 @@ public static partial class FastTree { [TlcModule.EntryPoint(Name = "Trainers.FastTreeRegressor", Desc = FastTreeRegressionTrainer.Summary, - Remarks = FastTreeRegressionTrainer.Remarks, UserName = FastTreeRegressionTrainer.UserNameValue, - ShortName = FastTreeRegressionTrainer.ShortName)] + ShortName = FastTreeRegressionTrainer.ShortName, + XmlInclude = new[] { @"" })] public static CommonOutputs.RegressionOutput TrainRegression(IHostEnvironment env, FastTreeRegressionTrainer.Arguments input) { Contracts.CheckValue(env, nameof(env)); diff --git a/src/Microsoft.ML.FastTree/FastTreeTweedie.cs b/src/Microsoft.ML.FastTree/FastTreeTweedie.cs index 6d9bd58273..b43c499a44 100644 --- a/src/Microsoft.ML.FastTree/FastTreeTweedie.cs +++ b/src/Microsoft.ML.FastTree/FastTreeTweedie.cs @@ -27,21 +27,15 @@ namespace Microsoft.ML.Runtime.FastTree { - /// - /// The Tweedie boosting model follows the mathematics established in: - /// Yang, Quan, and Zou. "Insurance Premium Prediction via Gradient Tree-Boosted Tweedie Compound Poisson Models." - /// https://arxiv.org/pdf/1508.06378.pdf - /// + // The Tweedie boosting model follows the mathematics established in: + // Yang, Quan, and Zou. "Insurance Premium Prediction via Gradient Tree-Boosted Tweedie Compound Poisson Models." + // https://arxiv.org/pdf/1508.06378.pdf + /// public sealed partial class FastTreeTweedieTrainer : BoostingFastTreeTrainerBase { public const string LoadNameValue = "FastTreeTweedieRegression"; public const string UserNameValue = "FastTree (Boosted Trees) Tweedie Regression"; public const string Summary = "Trains gradient boosted decision trees to fit target values using a Tweedie loss function. This learner is a generalization of Poisson, compound Poisson, and gamma regression."; - new public const string Remarks = @" -Wikipedia: Gradient boosting (Gradient tree boosting) -Greedy function approximation: A gradient boosting machine -"; - public const string ShortName = "fttweedie"; private TestHistory _firstTestSetHistory; @@ -466,7 +460,8 @@ public static partial class FastTree [TlcModule.EntryPoint(Name = "Trainers.FastTreeTweedieRegressor", Desc = FastTreeTweedieTrainer.Summary, UserName = FastTreeTweedieTrainer.UserNameValue, - ShortName = FastTreeTweedieTrainer.ShortName)] + ShortName = FastTreeTweedieTrainer.ShortName, + XmlInclude = new [] { @"" })] public static CommonOutputs.RegressionOutput TrainTweedieRegression(IHostEnvironment env, FastTreeTweedieTrainer.Arguments input) { Contracts.CheckValue(env, nameof(env)); diff --git a/src/Microsoft.ML.FastTree/RandomForest.cs b/src/Microsoft.ML.FastTree/RandomForest.cs index 2f670539b4..88676754d5 100644 --- a/src/Microsoft.ML.FastTree/RandomForest.cs +++ b/src/Microsoft.ML.FastTree/RandomForest.cs @@ -12,28 +12,6 @@ public abstract class RandomForestTrainerBase : FastTreeTrain where TArgs : FastForestArgumentsBase, new() where TPredictor : IPredictorProducing { - new internal const string Remarks = @" -Decision trees are non-parametric models that perform a sequence of simple tests on inputs. -This decision procedure maps them to outputs found in the training dataset whose inputs were similar to the instance being processed. -A decision is made at each node of the binary tree data structure based on a measure of similarity that maps each instance recursively through the branches of the tree until the appropriate leaf node is reached and the output decision returned. -Decision trees have several advantages: - -They are efficient in both computation and memory usage during training and prediction. -They can represent non-linear decision boundaries. -They perform integrated feature selection and classification. -They are resilient in the presence of noisy features. - -Fast forest is a random forest implementation. -The model consists of an ensemble of decision trees. Each tree in a decision forest outputs a Gaussian distribution by way of prediction. -An aggregation is performed over the ensemble of trees to find a Gaussian distribution closest to the combined distribution for all trees in the model. -This decision forest classifier consists of an ensemble of decision trees. -Generally, ensemble models provide better coverage and accuracy than single decision trees. -Each tree in a decision forest outputs a Gaussian distribution. -Wikipedia: Random forest -Quantile regression forest -From Stumps to Trees to Forests -"; - private readonly bool _quantileEnabled; protected RandomForestTrainerBase(IHostEnvironment env, TArgs args, bool quantileEnabled = false) diff --git a/src/Microsoft.ML.FastTree/RandomForestClassification.cs b/src/Microsoft.ML.FastTree/RandomForestClassification.cs index e3e265cf13..8cd62ceb77 100644 --- a/src/Microsoft.ML.FastTree/RandomForestClassification.cs +++ b/src/Microsoft.ML.FastTree/RandomForestClassification.cs @@ -106,6 +106,7 @@ public static IPredictorProducing Create(IHostEnvironment env, ModelLoadC } } + /// public sealed partial class FastForestClassification : RandomForestTrainerBase> { @@ -210,9 +211,9 @@ public static partial class FastForest { [TlcModule.EntryPoint(Name = "Trainers.FastForestBinaryClassifier", Desc = FastForestClassification.Summary, - Remarks = FastForestClassification.Remarks, UserName = FastForestClassification.UserNameValue, - ShortName = FastForestClassification.ShortName)] + ShortName = FastForestClassification.ShortName, + XmlInclude = new[] { @"" })] public static CommonOutputs.BinaryClassificationOutput TrainBinary(IHostEnvironment env, FastForestClassification.Arguments input) { Contracts.CheckValue(env, nameof(env)); diff --git a/src/Microsoft.ML.FastTree/RandomForestRegression.cs b/src/Microsoft.ML.FastTree/RandomForestRegression.cs index ef9b3e5e9b..f501037df3 100644 --- a/src/Microsoft.ML.FastTree/RandomForestRegression.cs +++ b/src/Microsoft.ML.FastTree/RandomForestRegression.cs @@ -137,6 +137,7 @@ public ISchemaBindableMapper CreateMapper(Double[] quantiles) } } + /// public sealed partial class FastForestRegression : RandomForestTrainerBase { public sealed class Arguments : FastForestArgumentsBase @@ -282,9 +283,9 @@ public static partial class FastForest { [TlcModule.EntryPoint(Name = "Trainers.FastForestRegressor", Desc = FastForestRegression.Summary, - Remarks = FastForestRegression.Remarks, UserName = FastForestRegression.LoadNameValue, - ShortName = FastForestRegression.ShortName)] + ShortName = FastForestRegression.ShortName, + XmlInclude = new[] { @"" })] public static CommonOutputs.RegressionOutput TrainRegression(IHostEnvironment env, FastForestRegression.Arguments input) { Contracts.CheckValue(env, nameof(env)); diff --git a/src/Microsoft.ML.FastTree/doc.xml b/src/Microsoft.ML.FastTree/doc.xml new file mode 100644 index 0000000000..36f0b41f24 --- /dev/null +++ b/src/Microsoft.ML.FastTree/doc.xml @@ -0,0 +1,78 @@ + + + + + + + Trains gradient boosted decision trees to the LambdaRank quasi-gradient. + + + + FastTree is an efficient implementation of the MART gradient boosting algorithm. + Gradient boosting is a machine learning technique for regression problems. + It builds each regression tree in a step-wise fashion, using a predefined loss function to measure the error for each step and corrects for it in the next. + So this prediction model is actually an ensemble of weaker prediction models. In regression problems, boosting builds a series of of such trees in a step-wise fashion and then selects the optimal tree using an arbitrary differentiable loss function. + + + MART learns an ensemble of regression trees, which is a decision tree with scalar values in its leaves. + A decision (or regression) tree is a binary tree-like flow chart, where at each interior node one decides which of the two child nodes to continue to based on one of the feature values from the input. + At each leaf node, a value is returned. In the interior nodes, the decision is based on the test 'x <= v' where x is the value of the feature in the input sample and v is one of the possible values of this feature. + The functions that can be produced by a regression tree are all the piece-wise constant functions. + + + The ensemble of trees is produced by computing, in each step, a regression tree that approximates the gradient of the loss function, and adding it to the previous tree with coefficients that minimize the loss of the new tree. + The output of the ensemble produced by MART on a given instance is the sum of the tree outputs. + + + In case of a binary classification problem, the output is converted to a probability by using some form of calibration. + In case of a regression problem, the output is the predicted value of the function. + In case of a ranking problem, the instances are ordered by the output value of the ensemble. + + Wikipedia: Gradient boosting (Gradient tree boosting). + Greedy function approximation: A gradient boosting machine.. + + + + + + Trains a random forest to fit target values using least-squares. + + + Decision trees are non-parametric models that perform a sequence of simple tests on inputs. + This decision procedure maps them to outputs found in the training dataset whose inputs were similar to the instance being processed. + A decision is made at each node of the binary tree data structure based on a measure of similarity that maps each instance recursively through the branches of the tree until the appropriate leaf node is reached and the output decision returned. + Decision trees have several advantages: + + They are efficient in both computation and memory usage during training and prediction. + They can represent non-linear decision boundaries. + They perform integrated feature selection and classification. + They are resilient in the presence of noisy features. + + Fast forest is a random forest implementation. + The model consists of an ensemble of decision trees. Each tree in a decision forest outputs a Gaussian distribution by way of prediction. + An aggregation is performed over the ensemble of trees to find a Gaussian distribution closest to the combined distribution for all trees in the model. + This decision forest classifier consists of an ensemble of decision trees. + Generally, ensemble models provide better coverage and accuracy than single decision trees. + Each tree in a decision forest outputs a Gaussian distribution. + Wikipedia: Random forest + Quantile regression forest + From Stumps to Trees to Forests + + + + + + Trains gradient boosted decision trees to fit target values using a Tweedie loss function. + This learner is a generalization of Poisson, compound Poisson, and gamma regression. + + + The Tweedie boosting model follows the mathematics established in + Insurance Premium Prediction via Gradient Tree-Boosted Tweedie Compound Poisson Models. from Yang, Quan, and Zou. + For an introduction to Gradient Boosting, and more information, see: + Wikipedia: Gradient boosting (Gradient tree boosting) + Greedy function approximation: A gradient boosting machine + + + + + \ No newline at end of file diff --git a/src/Microsoft.ML.KMeansClustering/KMeansPlusPlusTrainer.cs b/src/Microsoft.ML.KMeansClustering/KMeansPlusPlusTrainer.cs index ff663a8d6e..dce7be48d2 100644 --- a/src/Microsoft.ML.KMeansClustering/KMeansPlusPlusTrainer.cs +++ b/src/Microsoft.ML.KMeansClustering/KMeansPlusPlusTrainer.cs @@ -28,6 +28,7 @@ namespace Microsoft.ML.Runtime.KMeans { + /// public class KMeansPlusPlusTrainer : TrainerBase { public const string LoadNameValue = "KMeansPlusPlus"; @@ -36,14 +37,6 @@ public class KMeansPlusPlusTrainer : TrainerBase -K-means++ improves upon K-means by using the Yinyang K-Means method for choosing the initial cluster centers. -YYK-Means accelerates K-Means up to an order of magnitude while producing exactly the same clustering results (modulo floating point precision issues). -YYK-Means observes that there is a lot of redundancy across iterations in the KMeans algorithms and most points do not change their clusters during an iteration. -It uses various bounding techniques to identify this redundancy and eliminate many distance computations and optimize centroid computations. -K-means. -K-means++ -"; public enum InitAlgorithm { @@ -218,9 +211,9 @@ private static int ComputeNumThreads(IHost host, int? argNumThreads) [TlcModule.EntryPoint(Name = "Trainers.KMeansPlusPlusClusterer", Desc = Summary, - Remarks = Remarks, UserName = UserNameValue, - ShortName = ShortName)] + ShortName = ShortName, + XmlInclude = new[] { @"" })] public static CommonOutputs.ClusteringOutput TrainKMeans(IHostEnvironment env, Arguments input) { Contracts.CheckValue(env, nameof(env)); diff --git a/src/Microsoft.ML.KMeansClustering/doc.xml b/src/Microsoft.ML.KMeansClustering/doc.xml new file mode 100644 index 0000000000..affaeabf98 --- /dev/null +++ b/src/Microsoft.ML.KMeansClustering/doc.xml @@ -0,0 +1,22 @@ + + + + + + + K-means is a popular clustering algorithm. With K-means, the data is clustered into a specified + number of clusters in order to minimize the within-cluster sum of squares. + + + K-means++ improves upon K-means by using the Yinyang K-Means method for choosing the initial cluster centers. + YYK-Means accelerates K-Means up to an order of magnitude while producing exactly the same clustering results (modulo floating point precision issues). + YYK-Means observes that there is a lot of redundancy across iterations in the KMeans algorithms and most points do not change their clusters during an iteration. + It uses various bounding techniques to identify this redundancy and eliminate many distance computations and optimize centroid computations. + For more information on K-means, and K-means++ see: + K-means. + K-means++ + + + + + \ No newline at end of file diff --git a/src/Microsoft.ML.LightGBM/LightGbmBinaryTrainer.cs b/src/Microsoft.ML.LightGBM/LightGbmBinaryTrainer.cs index 0b71bfa70e..54cd523e72 100644 --- a/src/Microsoft.ML.LightGBM/LightGbmBinaryTrainer.cs +++ b/src/Microsoft.ML.LightGBM/LightGbmBinaryTrainer.cs @@ -81,6 +81,7 @@ public static IPredictorProducing Create(IHostEnvironment env, ModelLoadC public override PredictionKind PredictionKind { get { return PredictionKind.BinaryClassification; } } } + /// public sealed class LightGbmBinaryTrainer : LightGbmTrainerBase> { internal const string UserName = "LightGBM Binary Classifier"; @@ -131,9 +132,9 @@ public static partial class LightGbm [TlcModule.EntryPoint( Name = "Trainers.LightGbmBinaryClassifier", Desc = LightGbmBinaryTrainer.Summary, - Remarks = LightGbmBinaryTrainer.Remarks, UserName = LightGbmBinaryTrainer.UserName, - ShortName = LightGbmBinaryTrainer.ShortName)] + ShortName = LightGbmBinaryTrainer.ShortName, + XmlInclude = new[] { @"" })] public static CommonOutputs.BinaryClassificationOutput TrainBinary(IHostEnvironment env, LightGbmArguments input) { Contracts.CheckValue(env, nameof(env)); diff --git a/src/Microsoft.ML.LightGBM/LightGbmMulticlassTrainer.cs b/src/Microsoft.ML.LightGBM/LightGbmMulticlassTrainer.cs index 479be65bec..2a84bad0e8 100644 --- a/src/Microsoft.ML.LightGBM/LightGbmMulticlassTrainer.cs +++ b/src/Microsoft.ML.LightGBM/LightGbmMulticlassTrainer.cs @@ -18,6 +18,7 @@ namespace Microsoft.ML.Runtime.LightGBM { + /// public sealed class LightGbmMulticlassTrainer : LightGbmTrainerBase, OvaPredictor> { public const string Summary = "LightGBM Multi Class Classifier"; @@ -182,9 +183,9 @@ public static partial class LightGbm [TlcModule.EntryPoint( Name = "Trainers.LightGbmClassifier", Desc = "Train a LightGBM multi class model.", - Remarks = LightGbmMulticlassTrainer.Remarks, UserName = LightGbmMulticlassTrainer.Summary, - ShortName = LightGbmMulticlassTrainer.ShortName)] + ShortName = LightGbmMulticlassTrainer.ShortName, + XmlInclude = new[] { @"" })] public static CommonOutputs.MulticlassClassificationOutput TrainMultiClass(IHostEnvironment env, LightGbmArguments input) { Contracts.CheckValue(env, nameof(env)); diff --git a/src/Microsoft.ML.LightGBM/LightGbmRankingTrainer.cs b/src/Microsoft.ML.LightGBM/LightGbmRankingTrainer.cs index 2ed436b4eb..4a1d1634a8 100644 --- a/src/Microsoft.ML.LightGBM/LightGbmRankingTrainer.cs +++ b/src/Microsoft.ML.LightGBM/LightGbmRankingTrainer.cs @@ -71,6 +71,7 @@ public static LightGbmRankingPredictor Create(IHostEnvironment env, ModelLoadCon public override PredictionKind PredictionKind { get { return PredictionKind.Ranking; } } } + /// public sealed class LightGbmRankingTrainer : LightGbmTrainerBase { public const string UserName = "LightGBM Ranking"; @@ -123,15 +124,15 @@ protected override void CheckAndUpdateParametersBeforeTraining(IChannel ch, Role } /// - /// A component to train a LightGBM model. + /// The entry point for the LightGbmRankingTrainer. /// public static partial class LightGbm { [TlcModule.EntryPoint(Name = "Trainers.LightGbmRanker", - Remarks = LightGbmMulticlassTrainer.Remarks, Desc = "Train a LightGBM ranking model.", UserName = LightGbmRankingTrainer.UserName, - ShortName = LightGbmRankingTrainer.ShortName)] + ShortName = LightGbmRankingTrainer.ShortName, + XmlInclude = new[] { @"" })] public static CommonOutputs.RankingOutput TrainRanking(IHostEnvironment env, LightGbmArguments input) { Contracts.CheckValue(env, nameof(env)); diff --git a/src/Microsoft.ML.LightGBM/LightGbmRegressionTrainer.cs b/src/Microsoft.ML.LightGBM/LightGbmRegressionTrainer.cs index 36c82aa79a..6ae3da792a 100644 --- a/src/Microsoft.ML.LightGBM/LightGbmRegressionTrainer.cs +++ b/src/Microsoft.ML.LightGBM/LightGbmRegressionTrainer.cs @@ -20,7 +20,7 @@ namespace Microsoft.ML.Runtime.LightGBM { - + /// public sealed class LightGbmRegressionPredictor : FastTreePredictionWrapper { public const string LoaderSignature = "LightGBMRegressionExec"; @@ -122,9 +122,9 @@ public static partial class LightGbm { [TlcModule.EntryPoint(Name = "Trainers.LightGbmRegressor", Desc = LightGbmRegressorTrainer.Summary, - Remarks = LightGbmRegressorTrainer.Remarks, UserName = LightGbmRegressorTrainer.UserNameValue, - ShortName = LightGbmRegressorTrainer.ShortName)] + ShortName = LightGbmRegressorTrainer.ShortName, + XmlInclude = new[] { @"" })] public static CommonOutputs.RegressionOutput TrainRegression(IHostEnvironment env, LightGbmArguments input) { Contracts.CheckValue(env, nameof(env)); diff --git a/src/Microsoft.ML.LightGBM/LightGbmTrainerBase.cs b/src/Microsoft.ML.LightGBM/LightGbmTrainerBase.cs index a93fa2ad60..c778c4ee23 100644 --- a/src/Microsoft.ML.LightGBM/LightGbmTrainerBase.cs +++ b/src/Microsoft.ML.LightGBM/LightGbmTrainerBase.cs @@ -58,9 +58,6 @@ private sealed class CategoricalMetaData protected int FeatureCount; protected FastTree.Internal.Ensemble TrainedEnsemble; - internal const string Remarks = @"Light GBM is an open source implementation of boosted trees. -GitHub: LightGBM"; - #endregion protected LightGbmTrainerBase(IHostEnvironment env, LightGbmArguments args, PredictionKind predictionKind, string name) diff --git a/src/Microsoft.ML.LightGBM/doc.xml b/src/Microsoft.ML.LightGBM/doc.xml new file mode 100644 index 0000000000..4d53265ae3 --- /dev/null +++ b/src/Microsoft.ML.LightGBM/doc.xml @@ -0,0 +1,16 @@ + + + + + + + Trains a Light GBM Model. + + + Light GBM is an open source implementation of boosted trees. + GitHub: LightGBM + + + + + \ No newline at end of file diff --git a/src/Microsoft.ML.PCA/PcaTrainer.cs b/src/Microsoft.ML.PCA/PcaTrainer.cs index 6c114ef14d..23e7351a86 100644 --- a/src/Microsoft.ML.PCA/PcaTrainer.cs +++ b/src/Microsoft.ML.PCA/PcaTrainer.cs @@ -286,9 +286,9 @@ private static void PostProcess(VBuffer[] y, Float[] sigma, Float[] z, in [TlcModule.EntryPoint(Name = "Trainers.PcaAnomalyDetector", Desc = "Train an PCA Anomaly model.", - Remarks = PcaPredictor.Remarks, UserName = UserNameValue, - ShortName = ShortName)] + ShortName = ShortName, + XmlInclude = new[] { @"" })] public static CommonOutputs.AnomalyDetectionOutput TrainPcaAnomaly(IHostEnvironment env, Arguments input) { Contracts.CheckValue(env, nameof(env)); @@ -302,13 +302,13 @@ public static CommonOutputs.AnomalyDetectionOutput TrainPcaAnomaly(IHostEnvironm } } - /// - /// An anomaly detector using PCA. - /// - The algorithm uses the top eigenvectors to approximate the subspace containing the normal class - /// - For each new instance, it computes the norm difference between the raw feature vector and the projected feature on that subspace. - /// - - If the error is close to 0, the instance is considered normal (non-anomaly). - /// + // An anomaly detector using PCA. + // - The algorithm uses the top eigenvectors to approximate the subspace containing the normal class + // - For each new instance, it computes the norm difference between the raw feature vector and the projected feature on that subspace. + // - - If the error is close to 0, the instance is considered normal (non-anomaly). // REVIEW: move the predictor to a different file and fold EigenUtils.cs to this file. + // REVIEW: Include the above detail in the XML documentation file. + /// public sealed class PcaPredictor : PredictorBase, IValueMapper, ICanGetSummaryAsIDataView, @@ -316,14 +316,6 @@ public sealed class PcaPredictor : PredictorBase, { public const string LoaderSignature = "pcaAnomExec"; public const string RegistrationName = "PCAPredictor"; - internal const string Remarks = @" -Principle Component Analysis (PCA) is a dimensionality-reduction transform which computes the projection of the feature vector to onto a low-rank subspace. -Its training is done using the technique described in the paper: Combining Structured and Unstructured Randomness in Large Scale PCA, -and the paper Finding Structure with Randomness: Probabilistic Algorithms for Constructing Approximate Matrix Decompositions -Randomized Methods for Computing the Singular Value Decomposition (SVD) of very large matrices -A randomized algorithm for principal component analysis -Finding Structure with Randomness: Probabilistic Algorithms for Constructing Approximate Matrix Decompositions -"; private static VersionInfo GetVersionInfo() { diff --git a/src/Microsoft.ML.PCA/PcaTransform.cs b/src/Microsoft.ML.PCA/PcaTransform.cs index cef2264677..0807abc5ed 100644 --- a/src/Microsoft.ML.PCA/PcaTransform.cs +++ b/src/Microsoft.ML.PCA/PcaTransform.cs @@ -26,6 +26,7 @@ namespace Microsoft.ML.Runtime.Data { + /// public sealed class PcaTransform : OneToOneTransformBase { public sealed class Arguments : TransformInputBase @@ -536,8 +537,11 @@ private static void TransformFeatures(IExceptionContext ectx, ref VBuffer dst = new VBuffer(transformInfo.Rank, values, dst.Indices); } - [TlcModule.EntryPoint(Name = "Transforms.PcaCalculator", Desc = "Train an PCA Anomaly model.", - UserName = UserName, ShortName = ShortName)] + [TlcModule.EntryPoint(Name = "Transforms.PcaCalculator", + Desc = Summary, + UserName = UserName, + ShortName = ShortName, + XmlInclude = new[] { @"" })] public static CommonOutputs.TransformOutput Calculate(IHostEnvironment env, Arguments input) { var h = EntryPointUtils.CheckArgsAndCreateHost(env, "Pca", input); diff --git a/src/Microsoft.ML.PCA/doc.xml b/src/Microsoft.ML.PCA/doc.xml new file mode 100644 index 0000000000..98d423b754 --- /dev/null +++ b/src/Microsoft.ML.PCA/doc.xml @@ -0,0 +1,27 @@ + + + + + + + PCA is a dimensionality-reduction transform which computes the projection of the feature vector to onto a low-rank subspace. + + + Principle Component Analysis (PCA) is a dimensionality-reduction transform which computes the projection of the feature vector to onto a low-rank subspace. + Its training is done using the technique described in the paper: Combining Structured and Unstructured Randomness in Large Scale PCA, + and the paper Finding Structure with Randomness: Probabilistic Algorithms for Constructing Approximate Matrix Decompositions + Randomized Methods for Computing the Singular Value Decomposition (SVD) of very large matrices + A randomized algorithm for principal component analysis + Finding Structure with Randomness: Probabilistic Algorithms for Constructing Approximate Matrix Decompositions + + + An example of how to add the PcaCalculator transform to a pipeline with a column named "Features". + + string[] features = new string["Sepal length", "Sepal width", "Petal length", "Petal width"]; + pipeline.Add(new PcaCalculator(columns){ Rank = 3 }); + + + + + + \ No newline at end of file diff --git a/src/Microsoft.ML.StandardLearners/FactorizationMachine/FactorizationMachineTrainer.cs b/src/Microsoft.ML.StandardLearners/FactorizationMachine/FactorizationMachineTrainer.cs index 7a0a099031..b967bd9f95 100644 --- a/src/Microsoft.ML.StandardLearners/FactorizationMachine/FactorizationMachineTrainer.cs +++ b/src/Microsoft.ML.StandardLearners/FactorizationMachine/FactorizationMachineTrainer.cs @@ -22,13 +22,14 @@ namespace Microsoft.ML.Runtime.FactorizationMachine { - /// - /// Train a field-aware factorization machine using ADAGRAD (an advanced stochastic gradient method). See references below - /// for details. This trainer is essentially faster the one introduced in [2] because of some implemtation tricks[3]. - /// [1] http://jmlr.org/papers/volume12/duchi11a/duchi11a.pdf - /// [2] http://www.csie.ntu.edu.tw/~cjlin/papers/ffm.pdf - /// [3] https://github.com/wschin/fast-ffm/blob/master/fast-ffm.pdf - /// + /* + Train a field-aware factorization machine using ADAGRAD (an advanced stochastic gradient method). See references below + for details. This trainer is essentially faster the one introduced in [2] because of some implemtation tricks[3]. + [1] http://jmlr.org/papers/volume12/duchi11a/duchi11a.pdf + [2] http://www.csie.ntu.edu.tw/~cjlin/papers/ffm.pdf + [3] https://github.com/wschin/fast-ffm/blob/master/fast-ffm.pdf + */ + /// public sealed class FieldAwareFactorizationMachineTrainer : TrainerBase, IIncrementalTrainer, IValidatingTrainer, IIncrementalValidatingTrainer @@ -37,15 +38,6 @@ public sealed class FieldAwareFactorizationMachineTrainer : TrainerBase -Field Aware Factorization Machines use, in addition to the input variables, factorized parameters to model the interaction between pairs of variables. -The algorithm is particularly useful for high dimensional datasets which can be very sparse (e.g. click-prediction for advertising systems). -An advantage of FFM over SVMs is that the training data does not need to be stored in memory, and the coefficients can be optimized directly. -Field Aware Factorization Machines -Field-aware Factorization Machines for CTR Prediction -Adaptive Subgradient Methods for Online Learning and Stochastic Optimization -An Improved Stochastic Gradient Method for Training Large-scale Field-aware Factorization Machine. -"; public sealed class Arguments : LearnerInputBaseWithLabel { @@ -413,9 +405,9 @@ public override FieldAwareFactorizationMachinePredictor CreatePredictor() [TlcModule.EntryPoint(Name = "Trainers.FieldAwareFactorizationMachineBinaryClassifier", Desc = Summary, - Remarks = Remarks, UserName = UserName, - ShortName = ShortName)] + ShortName = ShortName, + XmlInclude = new[] { @"" })] public static CommonOutputs.BinaryClassificationOutput TrainBinary(IHostEnvironment env, Arguments input) { Contracts.CheckValue(env, nameof(env)); diff --git a/src/Microsoft.ML.StandardLearners/FactorizationMachine/doc.xml b/src/Microsoft.ML.StandardLearners/FactorizationMachine/doc.xml new file mode 100644 index 0000000000..2e72b2ea9f --- /dev/null +++ b/src/Microsoft.ML.StandardLearners/FactorizationMachine/doc.xml @@ -0,0 +1,42 @@ + + + + + + + Train a field-aware factorization machine for binary classification using ADAGRAD (an advanced stochastic gradient method). + + + Field Aware Factorization Machines use, in addition to the input variables, factorized parameters to model the interaction between pairs of variables. + The algorithm is particularly useful for high dimensional datasets which can be very sparse (e.g. click-prediction for advertising systems). + An advantage of FFM over SVMs is that the training data does not need to be stored in memory, and the coefficients can be optimized directly. + For a general idea of what Field-aware Factorization Machines are see: Field Aware Factorization Machines + + See references below for more details. + This trainer is essentially faster the one introduced in [2] because of some implemtation tricks[3]. + + + + + [1] Field-aware Factorization Machines for CTR Prediction + + + [2] Adaptive Subgradient Methods for Online Learning and Stochastic Optimization + + + + + [3] An Improved Stochastic Gradient Method for Training Large-scale Field-aware Factorization Machine. + + + + + + + pipeline.Add(new FieldAwareFactorizationMachineBinaryClassifier(){ LearningRate = 0.5f, Iter=2 }); + + + + + + \ No newline at end of file diff --git a/src/Microsoft.ML.StandardLearners/Standard/LinearClassificationTrainer.cs b/src/Microsoft.ML.StandardLearners/Standard/LinearClassificationTrainer.cs index a48a53ae65..554babf1ce 100644 --- a/src/Microsoft.ML.StandardLearners/Standard/LinearClassificationTrainer.cs +++ b/src/Microsoft.ML.StandardLearners/Standard/LinearClassificationTrainer.cs @@ -222,26 +222,6 @@ internal virtual void Check(IHostEnvironment env) } } - internal const string Remarks = @" -This classifier is a trainer based on the Stochastic DualCoordinate Ascent(SDCA) method, a state-of-the-art optimization technique for convex objective functions. -The algorithm can be scaled for use on large out-of-memory data sets due to a semi-asynchronized implementation -that supports multi-threading. - -Convergence is underwritten by periodically enforcing synchronization between primal and dual updates in a separate thread. -Several choices of loss functions are also provided. -The SDCA method combines several of the best properties and capabilities of logistic regression and SVM algorithms. - - -Note that SDCA is a stochastic and streaming optimization algorithm. -The results depends on the order of the training data. For reproducible results, it is recommended that one sets to -False and to 1. -Elastic net regularization can be specified by the and parameters. Note that the has an effect on the rate of convergence. -In general, the larger the , the faster SDCA converges. - -Scaling Up Stochastic Dual Coordinate Ascent. -Stochastic Dual Coordinate Ascent Methods for Regularized Loss Minimization. -"; - // The order of these matter, since they are used as indices into arrays. protected enum MetricKind { @@ -1797,9 +1777,9 @@ public static partial class Sdca { [TlcModule.EntryPoint(Name = "Trainers.StochasticDualCoordinateAscentBinaryClassifier", Desc = "Train an SDCA binary model.", - Remarks = LinearClassificationTrainer.Remarks, UserName = LinearClassificationTrainer.UserNameValue, - ShortName = LinearClassificationTrainer.LoadNameValue)] + ShortName = LinearClassificationTrainer.LoadNameValue, + XmlInclude = new[] { @"" })] public static CommonOutputs.BinaryClassificationOutput TrainBinary(IHostEnvironment env, LinearClassificationTrainer.Arguments input) { Contracts.CheckValue(env, nameof(env)); diff --git a/src/Microsoft.ML.StandardLearners/Standard/LogisticRegression/LbfgsPredictorBase.cs b/src/Microsoft.ML.StandardLearners/Standard/LogisticRegression/LbfgsPredictorBase.cs index 95982047aa..89f4866228 100644 --- a/src/Microsoft.ML.StandardLearners/Standard/LogisticRegression/LbfgsPredictorBase.cs +++ b/src/Microsoft.ML.StandardLearners/Standard/LogisticRegression/LbfgsPredictorBase.cs @@ -94,35 +94,6 @@ public abstract class ArgumentsBase : LearnerInputBaseWithWeight public bool EnforceNonNegativity = false; } - internal const string Remarks = @" -If the dependent variable has more than two possible values (blood type given diagnostic test results), then the logistic regression is multinomial. - -The optimization technique used for LogisticRegressionBinaryClassifier is the limited memory Broyden-Fletcher-Goldfarb-Shanno (L-BFGS). -Both the L-BFGS and regular BFGS algorithms use quasi-Newtonian methods to estimate the computationally intensive Hessian matrix in the equation used by Newton's method to calculate steps. -But the L-BFGS approximation uses only a limited amount of memory to compute the next step direction, -so that it is especially suited for problems with a large number of variables. -The MemorySize parameter specifies the number of past positions and gradients to store for use in the computation of the next step. - - -This learner can use elastic net regularization: a linear combination of L1 (lasso) and L2 (ridge) regularizations. -Regularization is a method that can render an ill-posed problem more tractable by imposing constraints that provide information to supplement the data and that prevents overfitting by penalizing models with extreme coefficient values. -This can improve the generalization of the model learned by selecting the optimal complexity in the bias-variance tradeoff. -Regularization works by adding the penalty that is associated with coefficient values to the error of the hypothesis. -An accurate model with extreme coefficient values would be penalized more, but a less accurate model with more conservative values would be penalized less. L1 and L2 regularization have different effects and uses that are complementary in certain respects. - -L1Weight: can be applied to sparse models, when working with high-dimensional data. -It pulls small weights associated features that are relatively unimportant towards 0. -L2Weight: is preferable for data that is not sparse. It pulls large weights towards zero. - -Adding the ridge penalty to the regularization overcomes some of lasso's limitations. It can improve its predictive accuracy, for example, when the number of predictors is greater than the sample size. If x = l1_weight and y = l2_weight, ax + by = c defines the linear span of the regularization terms. -The default values of x and y are both 1. -An agressive regularization can harm predictive capacity by excluding important variables out of the model. So choosing the optimal values for the regularization parameters is important for the performance of the logistic regression model. -Scalable Training of L1-Regularized Log-Linear Models. -Test Run - L1 and L2 Regularization for Machine Learning. -Wikipedia: L-BFGS. -Wikipedia: Logistic regression. -"; - protected int NumFeatures; protected VBuffer CurrentWeights; protected long NumGoodRows; diff --git a/src/Microsoft.ML.StandardLearners/Standard/LogisticRegression/LogisticRegression.cs b/src/Microsoft.ML.StandardLearners/Standard/LogisticRegression/LogisticRegression.cs index f1d35950ba..3cf97ea801 100644 --- a/src/Microsoft.ML.StandardLearners/Standard/LogisticRegression/LogisticRegression.cs +++ b/src/Microsoft.ML.StandardLearners/Standard/LogisticRegression/LogisticRegression.cs @@ -30,6 +30,8 @@ namespace Microsoft.ML.Runtime.Learners { using Mkl = Microsoft.ML.Runtime.Learners.OlsLinearRegressionTrainer.Mkl; + /// + /// public sealed partial class LogisticRegression : LbfgsTrainerBase { public const string LoadNameValue = "LogisticRegression"; @@ -388,9 +390,11 @@ public override ParameterMixingCalibratedPredictor CreatePredictor() [TlcModule.EntryPoint(Name = "Trainers.LogisticRegressionBinaryClassifier", Desc = Summary, - Remarks = Remarks, UserName = UserNameValue, - ShortName = ShortName)] + ShortName = ShortName, + XmlInclude = new[] { @"", + @""})] + public static CommonOutputs.BinaryClassificationOutput TrainBinary(IHostEnvironment env, Arguments input) { Contracts.CheckValue(env, nameof(env)); diff --git a/src/Microsoft.ML.StandardLearners/Standard/LogisticRegression/MulticlassLogisticRegression.cs b/src/Microsoft.ML.StandardLearners/Standard/LogisticRegression/MulticlassLogisticRegression.cs index 3cf22d98fa..66c1d41084 100644 --- a/src/Microsoft.ML.StandardLearners/Standard/LogisticRegression/MulticlassLogisticRegression.cs +++ b/src/Microsoft.ML.StandardLearners/Standard/LogisticRegression/MulticlassLogisticRegression.cs @@ -36,6 +36,8 @@ namespace Microsoft.ML.Runtime.Learners { + /// + /// public sealed class MulticlassLogisticRegression : LbfgsTrainerBase, MulticlassLogisticRegressionPredictor> { public const string LoadNameValue = "MultiClassLogisticRegression"; @@ -962,9 +964,10 @@ public partial class LogisticRegression { [TlcModule.EntryPoint(Name = "Trainers.LogisticRegressionClassifier", Desc = Summary, - Remarks = MulticlassLogisticRegression.Remarks, UserName = MulticlassLogisticRegression.UserNameValue, - ShortName = MulticlassLogisticRegression.ShortName)] + ShortName = MulticlassLogisticRegression.ShortName, + XmlInclude = new[] { @"", + @"" })] public static CommonOutputs.MulticlassClassificationOutput TrainMultiClass(IHostEnvironment env, MulticlassLogisticRegression.Arguments input) { Contracts.CheckValue(env, nameof(env)); diff --git a/src/Microsoft.ML.StandardLearners/Standard/LogisticRegression/doc.xml b/src/Microsoft.ML.StandardLearners/Standard/LogisticRegression/doc.xml new file mode 100644 index 0000000000..5ac68e2fc0 --- /dev/null +++ b/src/Microsoft.ML.StandardLearners/Standard/LogisticRegression/doc.xml @@ -0,0 +1,67 @@ + + + + + + + Logistic Regression is a method in statistics used to predict the probability of occurrence of an event and can be used as a classification algorithm. + The algorithm predicts the probability of occurrence of an event by fitting data to a logistical function. + + + If the dependent variable has more than two possible values (blood type given diagnostic test results), then the logistic regression is multinomial. + + The optimization technique used for LogisticRegression Classifier is the limited memory Broyden-Fletcher-Goldfarb-Shanno (L-BFGS). + Both the L-BFGS and regular BFGS algorithms use quasi-Newtonian methods to estimate the computationally intensive Hessian matrix in the equation used by Newton's method to calculate steps. + But the L-BFGS approximation uses only a limited amount of memory to compute the next step direction, + so that it is especially suited for problems with a large number of variables. + The MemorySize parameter specifies the number of past positions and gradients to store for use in the computation of the next step. + + + This learner can use elastic net regularization: a linear combination of L1 (lasso) and L2 (ridge) regularizations. + Regularization is a method that can render an ill-posed problem more tractable by imposing constraints that provide information to supplement the data and that prevents overfitting by penalizing models with extreme coefficient values. + This can improve the generalization of the model learned by selecting the optimal complexity in the bias-variance tradeoff. + Regularization works by adding the penalty that is associated with coefficient values to the error of the hypothesis. + An accurate model with extreme coefficient values would be penalized more, but a less accurate model with more conservative values would be penalized less. L1 and L2 regularization have different effects and uses that are complementary in certain respects. + + + + + L1Weight: can be applied to sparse models, when working with high-dimensional data. + It pulls small weights associated features that are relatively unimportant towards 0. + + + + + L2Weight: is preferable for data that is not sparse. It pulls large weights towards zero. + + + + Adding the ridge penalty to the regularization overcomes some of lasso's limitations. It can improve its predictive accuracy, for example, when the number of predictors is greater than the sample size. If x = l1_weight and y = l2_weight, ax + by = c defines the linear span of the regularization terms. + The default values of x and y are both 1. + An agressive regularization can harm predictive capacity by excluding important variables out of the model. So choosing the optimal values for the regularization parameters is important for the performance of the logistic regression model. + For more information see: + + Scalable Training of L1-Regularized Log-Linear Models. + Test Run - L1 and L2 Regularization for Machine Learning. + Wikipedia: L-BFGS. + Wikipedia: Logistic regression. + + + + + + + pipeline.Add(new LogisticRegressionClassifier()); + + + + + + + pipeline.Add(new LogisticRegressionBinaryClassifier()); + + + + + + \ No newline at end of file diff --git a/src/Microsoft.ML.StandardLearners/Standard/Online/AveragedPerceptron.cs b/src/Microsoft.ML.StandardLearners/Standard/Online/AveragedPerceptron.cs index ac259f66db..aa5ecb67a5 100644 --- a/src/Microsoft.ML.StandardLearners/Standard/Online/AveragedPerceptron.cs +++ b/src/Microsoft.ML.StandardLearners/Standard/Online/AveragedPerceptron.cs @@ -23,13 +23,12 @@ namespace Microsoft.ML.Runtime.Learners { - /// - /// This is an averaged perceptron classifier. - /// Configurable subcomponents: - /// - Loss function. By default, hinge loss (aka max-margin avgd perceptron) - /// - Feature normalization. By default, rescaling between min and max values for every feature - /// - Prediction calibration to produce probabilities. Off by default, if on, uses exponential (aka Platt) calibration. - /// + // This is an averaged perceptron classifier. + // Configurable subcomponents: + // - Loss function. By default, hinge loss (aka max-margin avgd perceptron) + // - Feature normalization. By default, rescaling between min and max values for every feature + // - Prediction calibration to produce probabilities. Off by default, if on, uses exponential (aka Platt) calibration. + /// public sealed class AveragedPerceptronTrainer : AveragedLinearTrainer { @@ -37,25 +36,6 @@ public sealed class AveragedPerceptronTrainer : internal const string UserNameValue = "Averaged Perceptron"; internal const string ShortName = "ap"; internal const string Summary = "Averaged Perceptron Binary Classifier."; - internal const string Remarks = @" -Perceptron is a classification algorithm that makes its predictions based on a linear function. -I.e., for an instance with feature values f0, f1,..., f_D-1, , the prediction is given by the sign of sigma[0,D-1] ( w_i * f_i), where w_0, w_1,...,w_D-1 are the weights computed by the algorithm. - -Perceptron is an online algorithm, i.e., it processes the instances in the training set one at a time. -The weights are initialized to be 0, or some random values. Then, for each example in the training set, the value of sigma[0, D-1] (w_i * f_i) is computed. -If this value has the same sign as the label of the current example, the weights remain the same. If they have opposite signs, -the weights vector is updated by either subtracting or adding (if the label is negative or positive, respectively) the feature vector of the current example, -multiplied by a factor 0 < a <= 1, called the learning rate. In a generalization of this algorithm, the weights are updated by adding the feature vector multiplied by the learning rate, -and by the gradient of some loss function (in the specific case described above, the loss is hinge-loss, whose gradient is 1 when it is non-zero). - - -In Averaged Perceptron (AKA voted-perceptron), the weight vectors are stored, -together with a weight that counts the number of iterations it survived (this is equivalent to storing the weight vector after every iteration, regardless of whether it was updated or not). -The prediction is then calculated by taking the weighted average of all the sums sigma[0, D-1] (w_i * f_i) or the different weight vectors. - -Wikipedia entry for Perceptron -Large Margin Classification Using the Perceptron Algorithm -"; public class Arguments : AveragedLinearArguments { @@ -112,9 +92,9 @@ public override LinearBinaryPredictor CreatePredictor() [TlcModule.EntryPoint(Name = "Trainers.AveragedPerceptronBinaryClassifier", Desc = Summary, - Remarks = Remarks, UserName = UserNameValue, - ShortName = ShortName)] + ShortName = ShortName, + XmlInclude = new[] { @"" })] public static CommonOutputs.BinaryClassificationOutput TrainBinary(IHostEnvironment env, Arguments input) { Contracts.CheckValue(env, nameof(env)); diff --git a/src/Microsoft.ML.StandardLearners/Standard/Online/OnlineGradientDescent.cs b/src/Microsoft.ML.StandardLearners/Standard/Online/OnlineGradientDescent.cs index dee63ccf37..f345466e19 100644 --- a/src/Microsoft.ML.StandardLearners/Standard/Online/OnlineGradientDescent.cs +++ b/src/Microsoft.ML.StandardLearners/Standard/Online/OnlineGradientDescent.cs @@ -27,6 +27,7 @@ namespace Microsoft.ML.Runtime.Learners { using TPredictor = LinearRegressionPredictor; + /// public sealed class OnlineGradientDescentTrainer : AveragedLinearTrainer { internal const string LoadNameValue = "OnlineGradientDescent"; @@ -34,11 +35,6 @@ public sealed class OnlineGradientDescentTrainer : AveragedLinearTrainer -Stochastic gradient descent uses a simple yet efficient iterative technique to fit model coefficients using error gradients for convex loss functions. -The OnlineGradientDescentRegressor implements the standard (non-batch) SGD, with a choice of loss functions, -and an option to update the weight vector using the average of the vectors seen over time (averaged argument is set to True by default). -"; public sealed class Arguments : AveragedLinearArguments { @@ -96,9 +92,9 @@ public override TPredictor CreatePredictor() [TlcModule.EntryPoint(Name = "Trainers.OnlineGradientDescentRegressor", Desc = "Train a Online gradient descent perceptron.", - Remarks = Remarks, UserName = UserNameValue, - ShortName = ShortName)] + ShortName = ShortName, + XmlInclude = new[] { @"" })] public static CommonOutputs.RegressionOutput TrainRegression(IHostEnvironment env, Arguments input) { Contracts.CheckValue(env, nameof(env)); diff --git a/src/Microsoft.ML.StandardLearners/Standard/Online/doc.xml b/src/Microsoft.ML.StandardLearners/Standard/Online/doc.xml new file mode 100644 index 0000000000..1ab7647c4f --- /dev/null +++ b/src/Microsoft.ML.StandardLearners/Standard/Online/doc.xml @@ -0,0 +1,44 @@ + + + + + + + Stochastic gradient descent is an optimization method used to train a wide range of models in machine learning. + In the ML.Net the implementation of OGD, it is for linear regression. + + + Stochastic gradient descent uses a simple yet efficient iterative technique to fit model coefficients using error gradients for convex loss functions. + The OnlineGradientDescentRegressor implements the standard (non-batch) SGD, with a choice of loss functions, + and an option to update the weight vector using the average of the vectors seen over time (averaged argument is set to True by default). + + + + + + Averaged Perceptron Binary Classifier. + + + Perceptron is a classification algorithm that makes its predictions based on a linear function. + I.e., for an instance with feature values f0, f1,..., f_D-1, , the prediction is given by the sign of sigma[0,D-1] ( w_i * f_i), where w_0, w_1,...,w_D-1 are the weights computed by the algorithm. + + Perceptron is an online algorithm, i.e., it processes the instances in the training set one at a time. + The weights are initialized to be 0, or some random values. Then, for each example in the training set, the value of sigma[0, D-1] (w_i * f_i) is computed. + If this value has the same sign as the label of the current example, the weights remain the same. If they have opposite signs, + the weights vector is updated by either subtracting or adding (if the label is negative or positive, respectively) the feature vector of the current example, + multiplied by a factor 0 < a <= 1, called the learning rate. In a generalization of this algorithm, the weights are updated by adding the feature vector multiplied by the learning rate, + and by the gradient of some loss function (in the specific case described above, the loss is hinge-loss, whose gradient is 1 when it is non-zero). + + + In Averaged Perceptron (AKA voted-perceptron), the weight vectors are stored, + together with a weight that counts the number of iterations it survived (this is equivalent to storing the weight vector after every iteration, regardless of whether it was updated or not). + The prediction is then calculated by taking the weighted average of all the sums sigma[0, D-1] (w_i * f_i) or the different weight vectors. + + For more information see: + Wikipedia entry for Perceptron + Large Margin Classification Using the Perceptron Algorithm + + + + + \ No newline at end of file diff --git a/src/Microsoft.ML.StandardLearners/Standard/PoissonRegression/PoissonRegression.cs b/src/Microsoft.ML.StandardLearners/Standard/PoissonRegression/PoissonRegression.cs index c5ad4b4495..9322c2cc75 100644 --- a/src/Microsoft.ML.StandardLearners/Standard/PoissonRegression/PoissonRegression.cs +++ b/src/Microsoft.ML.StandardLearners/Standard/PoissonRegression/PoissonRegression.cs @@ -26,17 +26,13 @@ namespace Microsoft.ML.Runtime.Learners { + /// public sealed class PoissonRegression : LbfgsTrainerBase { internal const string LoadNameValue = "PoissonRegression"; internal const string UserNameValue = "Poisson Regression"; internal const string ShortName = "PR"; internal const string Summary = "Poisson Regression assumes the unknown function, denoted Y has a Poisson distribution."; - new internal const string Remarks = @" -Poisson regression is a parameterized regression method. -It assumes that the log of the conditional mean of the dependent variable follows a linear function of the dependent variables. -Assuming that the dependent variable follows a Poisson distribution, the parameters of the regressor can be estimated by maximizing the likelihood of the obtained observations. -"; public sealed class Arguments : ArgumentsBase { @@ -129,7 +125,11 @@ protected override void ProcessPriorDistribution(Float label, Float weight) // No-op by design. } - [TlcModule.EntryPoint(Name = "Trainers.PoissonRegressor", Desc = "Train an Poisson regression model.", UserName = UserNameValue, ShortName = ShortName)] + [TlcModule.EntryPoint(Name = "Trainers.PoissonRegressor", + Desc = "Train an Poisson regression model.", + UserName = UserNameValue, + ShortName = ShortName, + XmlInclude = new[] { @"" })] public static CommonOutputs.RegressionOutput TrainRegression(IHostEnvironment env, Arguments input) { Contracts.CheckValue(env, nameof(env)); diff --git a/src/Microsoft.ML.StandardLearners/Standard/PoissonRegression/doc.xml b/src/Microsoft.ML.StandardLearners/Standard/PoissonRegression/doc.xml new file mode 100644 index 0000000000..4d2aeec579 --- /dev/null +++ b/src/Microsoft.ML.StandardLearners/Standard/PoissonRegression/doc.xml @@ -0,0 +1,17 @@ + + + + + + + Trains a Poisson Regression model. + + + Poisson regression is a parameterized regression method. + It assumes that the log of the conditional mean of the dependent variable follows a linear function of the dependent variables. + Assuming that the dependent variable follows a Poisson distribution, the parameters of the regressor can be estimated by maximizing the likelihood of the obtained observations. + + + + + \ No newline at end of file diff --git a/src/Microsoft.ML.StandardLearners/Standard/SdcaMultiClass.cs b/src/Microsoft.ML.StandardLearners/Standard/SdcaMultiClass.cs index 9b00251139..20bc349a7c 100644 --- a/src/Microsoft.ML.StandardLearners/Standard/SdcaMultiClass.cs +++ b/src/Microsoft.ML.StandardLearners/Standard/SdcaMultiClass.cs @@ -28,9 +28,8 @@ namespace Microsoft.ML.Runtime.Learners { using TVectorPredictor = IPredictorProducing>; - /// - /// SDCA linear multiclass trainer. - /// + // SDCA linear multiclass trainer. + /// public class SdcaMultiClassTrainer : SdcaTrainerBase, ITrainerEx { public const string LoadNameValue = "SDCAMC"; @@ -382,15 +381,15 @@ protected override Float GetInstanceWeight(FloatLabelCursor cursor) } /// - /// A component to train an SDCA model. + /// The Entry Point for SDCA multiclass. /// public static partial class Sdca { [TlcModule.EntryPoint(Name = "Trainers.StochasticDualCoordinateAscentClassifier", Desc = SdcaMultiClassTrainer.Summary, - Remarks = SdcaMultiClassTrainer.Remarks, UserName = SdcaMultiClassTrainer.UserNameValue, - ShortName = SdcaMultiClassTrainer.ShortName)] + ShortName = SdcaMultiClassTrainer.ShortName, + XmlInclude = new[] { @"" })] public static CommonOutputs.MulticlassClassificationOutput TrainMultiClass(IHostEnvironment env, SdcaMultiClassTrainer.Arguments input) { Contracts.CheckValue(env, nameof(env)); diff --git a/src/Microsoft.ML.StandardLearners/Standard/SdcaRegression.cs b/src/Microsoft.ML.StandardLearners/Standard/SdcaRegression.cs index 422b63f397..512818bba7 100644 --- a/src/Microsoft.ML.StandardLearners/Standard/SdcaRegression.cs +++ b/src/Microsoft.ML.StandardLearners/Standard/SdcaRegression.cs @@ -25,6 +25,7 @@ namespace Microsoft.ML.Runtime.Learners { using TScalarPredictor = IPredictorWithFeatureWeights; + /// public sealed class SdcaRegressionTrainer : SdcaTrainerBase, ITrainer, ITrainerEx { public const string LoadNameValue = "SDCAR"; @@ -127,15 +128,15 @@ protected override Float TuneDefaultL2(IChannel ch, int maxIterations, long rowC } /// - /// A component to train an SDCA model. + ///The Entry Point for the SDCA regressor. /// public static partial class Sdca { [TlcModule.EntryPoint(Name = "Trainers.StochasticDualCoordinateAscentRegressor", Desc = SdcaRegressionTrainer.Summary, - Remarks = SdcaRegressionTrainer.Remarks, UserName = SdcaRegressionTrainer.UserNameValue, - ShortName = SdcaRegressionTrainer.ShortName)] + ShortName = SdcaRegressionTrainer.ShortName, + XmlInclude = new[] { @"" })] public static CommonOutputs.RegressionOutput TrainRegression(IHostEnvironment env, SdcaRegressionTrainer.Arguments input) { Contracts.CheckValue(env, nameof(env)); diff --git a/src/Microsoft.ML.StandardLearners/Standard/doc.xml b/src/Microsoft.ML.StandardLearners/Standard/doc.xml new file mode 100644 index 0000000000..0b4336a96e --- /dev/null +++ b/src/Microsoft.ML.StandardLearners/Standard/doc.xml @@ -0,0 +1,30 @@ + + + + + + + Train an SDCA linear model. + + + This classifier is a trainer based on the Stochastic DualCoordinate Ascent(SDCA) method, a state-of-the-art optimization technique for convex objective functions. + The algorithm can be scaled for use on large out-of-memory data sets due to a semi-asynchronized implementation that supports multi-threading. + + Convergence is underwritten by periodically enforcing synchronization between primal and dual updates in a separate thread. + Several choices of loss functions are also provided. + The SDCA method combines several of the best properties and capabilities of logistic regression and SVM algorithms. + + + Note that SDCA is a stochastic and streaming optimization algorithm. + The results depends on the order of the training data. For reproducible results, it is recommended that one sets 'Shuffle' to + False and 'NumThreads' to 1. + Elastic net regularization can be specified by the 'L2Const' and 'L1Threshold' parameters. Note that the 'L2Const' has an effect on the rate of convergence. + In general, the larger the 'L2Const', the faster SDCA converges. + + Scaling Up Stochastic Dual Coordinate Ascent. + Stochastic Dual Coordinate Ascent Methods for Regularized Loss Minimization. + + + + + \ No newline at end of file diff --git a/src/Microsoft.ML.Transforms/CategoricalHashTransform.cs b/src/Microsoft.ML.Transforms/CategoricalHashTransform.cs index 42f506930a..f400d92a93 100644 --- a/src/Microsoft.ML.Transforms/CategoricalHashTransform.cs +++ b/src/Microsoft.ML.Transforms/CategoricalHashTransform.cs @@ -19,6 +19,7 @@ namespace Microsoft.ML.Runtime.Data { + /// public static class CategoricalHashTransform { public const int NumBitsLim = 31; // can't convert 31-bit hashes to indicator vectors, so max is 30 diff --git a/src/Microsoft.ML.Transforms/CategoricalTransform.cs b/src/Microsoft.ML.Transforms/CategoricalTransform.cs index 70eed46248..fc1382901b 100644 --- a/src/Microsoft.ML.Transforms/CategoricalTransform.cs +++ b/src/Microsoft.ML.Transforms/CategoricalTransform.cs @@ -21,19 +21,7 @@ [assembly: LoadableClass(typeof(void), typeof(Categorical), null, typeof(SignatureEntryPointModule), "Categorical")] namespace Microsoft.ML.Runtime.Data { - /// - /// Categorical trans. - /// Each column can specify an output kind, Bag, Ind, or Key. - /// Notes: - /// * Each column builds/uses exactly one "vocabulary" (dictionary). - /// * The Key output kind produces integer values and KeyType columns. - /// * The Key value is the one-based index of the slot set in the Ind/Bag options. - /// * In the Key option, not found is assigned the value zero. - /// * In the Ind/Bag options, not found results in an all zero bit vector. - /// * Ind and Bag differ simply in how the bit-vectors generated from individual slots are aggregated: - /// for Ind they are concatenated and for Bag they are added. - /// * When the source column is a singleton, the Ind and Bag options are identical. - /// + /// public static class CategoricalTransform { public enum OutputKind : byte @@ -255,7 +243,10 @@ public static IDataTransform CreateTransformCore( public static class Categorical { - [TlcModule.EntryPoint(Name = "Transforms.CategoricalOneHotVectorizer", Desc = "Encodes the categorical variable with one-hot encoding based on term dictionary", UserName = CategoricalTransform.UserName)] + [TlcModule.EntryPoint(Name = "Transforms.CategoricalOneHotVectorizer", + Desc = CategoricalTransform.Summary, + UserName = CategoricalTransform.UserName, + XmlInclude = new[] { @"" })] public static CommonOutputs.TransformOutput CatTransformDict(IHostEnvironment env, CategoricalTransform.Arguments input) { Contracts.CheckValue(env, nameof(env)); @@ -267,7 +258,10 @@ public static CommonOutputs.TransformOutput CatTransformDict(IHostEnvironment en return new CommonOutputs.TransformOutput { Model = new TransformModel(env, xf, input.Data), OutputData = xf }; } - [TlcModule.EntryPoint(Name = "Transforms.CategoricalHashOneHotVectorizer", Desc = "Encodes the categorical variable with hash-based encoding", UserName = CategoricalHashTransform.UserName)] + [TlcModule.EntryPoint(Name = "Transforms.CategoricalHashOneHotVectorizer", + Desc = CategoricalHashTransform.Summary, + UserName = CategoricalHashTransform.UserName , + XmlInclude = new[] { @"" })] public static CommonOutputs.TransformOutput CatTransformHash(IHostEnvironment env, CategoricalHashTransform.Arguments input) { Contracts.CheckValue(env, nameof(env)); diff --git a/src/Microsoft.ML.Transforms/doc.xml b/src/Microsoft.ML.Transforms/doc.xml new file mode 100644 index 0000000000..7482c3a272 --- /dev/null +++ b/src/Microsoft.ML.Transforms/doc.xml @@ -0,0 +1,52 @@ + + + + + + + Encodes the categorical variable with hash-based encoding. + + + CategoricalHashOneHotVectorizer converts a categorical value into an indicator array by hashing the + value and using the hash as an index in the bag. + If the input column is a vector, a single indicator bag is returned for it. + + + + pipeline.Add(new CategoricalHashOneHotVectorizer("Text1") { HashBits = 10, Seed = 314489979, OutputKind = CategoricalTransformOutputKind.Bag }); + + + + + + + Converts the categorical value into an indicator array by building a dictionary of categories based on the data and using the id in the dictionary as the index in the array + + + The CategoricalOneHotVectorizer transform passes through a data set, operating on text columns, to + build a dictionary of categories. + For each row, the entire text string appearing in the input column is defined as a category. + The output of this transform is an indicator vector. + Each slot in this vector corresponds to a category in the dictionary, so its length is the size of the built dictionary. + The CategoricalOneHotVectorizer can be applied to one or more columns, in which case it builds and uses a separate dictionary + for each column that it is applied to. + + The produces integer values and columns. + The Key value is the one-based index of the slot set in the Ind/Bag options. + If the Key option is not found, it is assigned the value zero. + In the , options are not found, they result in an all zero bit vector. + and differ simply in how the bit-vectors generated from individual slots are aggregated: + for Ind they are concatenated and for Bag they are added. + When the source column is a singleton, the Ind and Bag options are identical. + + + An example of how to add the CategoricalOneHotVectorizer transform to a pipeline with two text column + features named "Text1" and "Text2". + + pipeline.Add(new CategoricalOneHotVectorizer("Text1", "Text1")); + + + + + + \ No newline at end of file diff --git a/src/Microsoft.ML/CSharpApi.cs b/src/Microsoft.ML/CSharpApi.cs index a0f7f17975..b190750ca1 100644 --- a/src/Microsoft.ML/CSharpApi.cs +++ b/src/Microsoft.ML/CSharpApi.cs @@ -4095,28 +4095,7 @@ public sealed class Output namespace Trainers { - /// - /// Averaged Perceptron Binary Classifier. - /// - /// - /// Perceptron is a classification algorithm that makes its predictions based on a linear function. - /// I.e., for an instance with feature values f0, f1,..., f_D-1, , the prediction is given by the sign of sigma[0,D-1] ( w_i * f_i), where w_0, w_1,...,w_D-1 are the weights computed by the algorithm. - /// - /// Perceptron is an online algorithm, i.e., it processes the instances in the training set one at a time. - /// The weights are initialized to be 0, or some random values. Then, for each example in the training set, the value of sigma[0, D-1] (w_i * f_i) is computed. - /// If this value has the same sign as the label of the current example, the weights remain the same. If they have opposite signs, - /// the weights vector is updated by either subtracting or adding (if the label is negative or positive, respectively) the feature vector of the current example, - /// multiplied by a factor 0 < a <= 1, called the learning rate. In a generalization of this algorithm, the weights are updated by adding the feature vector multiplied by the learning rate, - /// and by the gradient of some loss function (in the specific case described above, the loss is hinge-loss, whose gradient is 1 when it is non-zero). - /// - /// - /// In Averaged Perceptron (AKA voted-perceptron), the weight vectors are stored, - /// together with a weight that counts the number of iterations it survived (this is equivalent to storing the weight vector after every iteration, regardless of whether it was updated or not). - /// The prediction is then calculated by taking the weighted average of all the sums sigma[0, D-1] (w_i * f_i) or the different weight vectors. - /// - /// Wikipedia entry for Perceptron - /// Large Margin Classification Using the Perceptron Algorithm - /// + /// public sealed partial class AveragedPerceptronBinaryClassifier : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithLabel, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInput, Microsoft.ML.ILearningPipelineItem { @@ -4620,30 +4599,7 @@ public enum Bundle : byte } - /// - /// Uses a random forest learner to perform binary classification. - /// - /// - /// Decision trees are non-parametric models that perform a sequence of simple tests on inputs. - /// This decision procedure maps them to outputs found in the training dataset whose inputs were similar to the instance being processed. - /// A decision is made at each node of the binary tree data structure based on a measure of similarity that maps each instance recursively through the branches of the tree until the appropriate leaf node is reached and the output decision returned. - /// Decision trees have several advantages: - /// - /// They are efficient in both computation and memory usage during training and prediction. - /// They can represent non-linear decision boundaries. - /// They perform integrated feature selection and classification. - /// They are resilient in the presence of noisy features. - /// - /// Fast forest is a random forest implementation. - /// The model consists of an ensemble of decision trees. Each tree in a decision forest outputs a Gaussian distribution by way of prediction. - /// An aggregation is performed over the ensemble of trees to find a Gaussian distribution closest to the combined distribution for all trees in the model. - /// This decision forest classifier consists of an ensemble of decision trees. - /// Generally, ensemble models provide better coverage and accuracy than single decision trees. - /// Each tree in a decision forest outputs a Gaussian distribution. - /// Wikipedia: Random forest - /// Quantile regression forest - /// From Stumps to Trees to Forests - /// + /// public sealed partial class FastForestBinaryClassifier : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithGroupId, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithWeight, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithLabel, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInput, Microsoft.ML.ILearningPipelineItem { @@ -4934,30 +4890,7 @@ public FastForestBinaryClassifierPipelineStep(Output output) namespace Trainers { - /// - /// Trains a random forest to fit target values using least-squares. - /// - /// - /// Decision trees are non-parametric models that perform a sequence of simple tests on inputs. - /// This decision procedure maps them to outputs found in the training dataset whose inputs were similar to the instance being processed. - /// A decision is made at each node of the binary tree data structure based on a measure of similarity that maps each instance recursively through the branches of the tree until the appropriate leaf node is reached and the output decision returned. - /// Decision trees have several advantages: - /// - /// They are efficient in both computation and memory usage during training and prediction. - /// They can represent non-linear decision boundaries. - /// They perform integrated feature selection and classification. - /// They are resilient in the presence of noisy features. - /// - /// Fast forest is a random forest implementation. - /// The model consists of an ensemble of decision trees. Each tree in a decision forest outputs a Gaussian distribution by way of prediction. - /// An aggregation is performed over the ensemble of trees to find a Gaussian distribution closest to the combined distribution for all trees in the model. - /// This decision forest classifier consists of an ensemble of decision trees. - /// Generally, ensemble models provide better coverage and accuracy than single decision trees. - /// Each tree in a decision forest outputs a Gaussian distribution. - /// Wikipedia: Random forest - /// Quantile regression forest - /// From Stumps to Trees to Forests - /// + /// public sealed partial class FastForestRegressor : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithGroupId, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithWeight, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithLabel, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInput, Microsoft.ML.ILearningPipelineItem { @@ -5244,33 +5177,7 @@ public enum BoostedTreeArgsOptimizationAlgorithmType } - /// - /// Uses a logit-boost boosted tree learner to perform binary classification. - /// - /// - /// FastTrees is an efficient implementation of the MART gradient boosting algorithm. - /// Gradient boosting is a machine learning technique for regression problems. - /// It builds each regression tree in a step-wise fashion, using a predefined loss function to measure the error for each step and corrects for it in the next. - /// So this prediction model is actually an ensemble of weaker prediction models. In regression problems, boosting builds a series of of such trees in a step-wise fashion and then selects the optimal tree using an arbitrary differentiable loss function. - /// - /// - /// MART learns an ensemble of regression trees, which is a decision tree with scalar values in its leaves. - /// A decision (or regression) tree is a binary tree-like flow chart, where at each interior node one decides which of the two child nodes to continue to based on one of the feature values from the input. - /// At each leaf node, a value is returned. In the interior nodes, the decision is based on the test 'x <= v' where x is the value of the feature in the input sample and v is one of the possible values of this feature. - /// The functions that can be produced by a regression tree are all the piece-wise constant functions. - /// - /// - /// The ensemble of trees is produced by computing, in each step, a regression tree that approximates the gradient of the loss function, and adding it to the previous tree with coefficients that minimize the loss of the new tree. - /// The output of the ensemble produced by MART on a given instance is the sum of the tree outputs. - /// - /// - /// In case of a binary classification problem, the output is converted to a probability by using some form of calibration. - /// In case of a regression problem, the output is the predicted value of the function. - /// In case of a ranking problem, the instances are ordered by the output value of the ensemble. - /// - /// Wikipedia: Gradient boosting (Gradient tree boosting). - /// Greedy function approximation: A gradient boosting machine.. - /// + /// public sealed partial class FastTreeBinaryClassifier : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithGroupId, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithWeight, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithLabel, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInput, Microsoft.ML.ILearningPipelineItem { @@ -5659,33 +5566,7 @@ public FastTreeBinaryClassifierPipelineStep(Output output) namespace Trainers { - /// - /// Trains gradient boosted decision trees to the LambdaRank quasi-gradient. - /// - /// - /// FastTrees is an efficient implementation of the MART gradient boosting algorithm. - /// Gradient boosting is a machine learning technique for regression problems. - /// It builds each regression tree in a step-wise fashion, using a predefined loss function to measure the error for each step and corrects for it in the next. - /// So this prediction model is actually an ensemble of weaker prediction models. In regression problems, boosting builds a series of of such trees in a step-wise fashion and then selects the optimal tree using an arbitrary differentiable loss function. - /// - /// - /// MART learns an ensemble of regression trees, which is a decision tree with scalar values in its leaves. - /// A decision (or regression) tree is a binary tree-like flow chart, where at each interior node one decides which of the two child nodes to continue to based on one of the feature values from the input. - /// At each leaf node, a value is returned. In the interior nodes, the decision is based on the test 'x <= v' where x is the value of the feature in the input sample and v is one of the possible values of this feature. - /// The functions that can be produced by a regression tree are all the piece-wise constant functions. - /// - /// - /// The ensemble of trees is produced by computing, in each step, a regression tree that approximates the gradient of the loss function, and adding it to the previous tree with coefficients that minimize the loss of the new tree. - /// The output of the ensemble produced by MART on a given instance is the sum of the tree outputs. - /// - /// - /// In case of a binary classification problem, the output is converted to a probability by using some form of calibration. - /// In case of a regression problem, the output is the predicted value of the function. - /// In case of a ranking problem, the instances are ordered by the output value of the ensemble. - /// - /// Wikipedia: Gradient boosting (Gradient tree boosting). - /// Greedy function approximation: A gradient boosting machine.. - /// + /// public sealed partial class FastTreeRanker : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithGroupId, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithWeight, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithLabel, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInput, Microsoft.ML.ILearningPipelineItem { @@ -6109,33 +5990,7 @@ public FastTreeRankerPipelineStep(Output output) namespace Trainers { - /// - /// Trains gradient boosted decision trees to fit target values using least-squares. - /// - /// - /// FastTrees is an efficient implementation of the MART gradient boosting algorithm. - /// Gradient boosting is a machine learning technique for regression problems. - /// It builds each regression tree in a step-wise fashion, using a predefined loss function to measure the error for each step and corrects for it in the next. - /// So this prediction model is actually an ensemble of weaker prediction models. In regression problems, boosting builds a series of of such trees in a step-wise fashion and then selects the optimal tree using an arbitrary differentiable loss function. - /// - /// - /// MART learns an ensemble of regression trees, which is a decision tree with scalar values in its leaves. - /// A decision (or regression) tree is a binary tree-like flow chart, where at each interior node one decides which of the two child nodes to continue to based on one of the feature values from the input. - /// At each leaf node, a value is returned. In the interior nodes, the decision is based on the test 'x <= v' where x is the value of the feature in the input sample and v is one of the possible values of this feature. - /// The functions that can be produced by a regression tree are all the piece-wise constant functions. - /// - /// - /// The ensemble of trees is produced by computing, in each step, a regression tree that approximates the gradient of the loss function, and adding it to the previous tree with coefficients that minimize the loss of the new tree. - /// The output of the ensemble produced by MART on a given instance is the sum of the tree outputs. - /// - /// - /// In case of a binary classification problem, the output is converted to a probability by using some form of calibration. - /// In case of a regression problem, the output is the predicted value of the function. - /// In case of a ranking problem, the instances are ordered by the output value of the ensemble. - /// - /// Wikipedia: Gradient boosting (Gradient tree boosting). - /// Greedy function approximation: A gradient boosting machine.. - /// + /// public sealed partial class FastTreeRegressor : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithGroupId, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithWeight, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithLabel, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInput, Microsoft.ML.ILearningPipelineItem { @@ -6519,9 +6374,7 @@ public FastTreeRegressorPipelineStep(Output output) namespace Trainers { - /// - /// Trains gradient boosted decision trees to fit target values using a Tweedie loss function. This learner is a generalization of Poisson, compound Poisson, and gamma regression. - /// + /// public sealed partial class FastTreeTweedieRegressor : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithGroupId, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithWeight, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithLabel, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInput, Microsoft.ML.ILearningPipelineItem { @@ -6910,18 +6763,7 @@ public FastTreeTweedieRegressorPipelineStep(Output output) namespace Trainers { - /// - /// Train a field-aware factorization machine for binary classification - /// - /// - /// Field Aware Factorization Machines use, in addition to the input variables, factorized parameters to model the interaction between pairs of variables. - /// The algorithm is particularly useful for high dimensional datasets which can be very sparse (e.g. click-prediction for advertising systems). - /// An advantage of FFM over SVMs is that the training data does not need to be stored in memory, and the coefficients can be optimized directly. - /// Field Aware Factorization Machines - /// Field-aware Factorization Machines for CTR Prediction - /// Adaptive Subgradient Methods for Online Learning and Stochastic Optimization - /// An Improved Stochastic Gradient Method for Training Large-scale Field-aware Factorization Machine. - /// + /// public sealed partial class FieldAwareFactorizationMachineBinaryClassifier : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithLabel, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInput, Microsoft.ML.ILearningPipelineItem { @@ -7348,17 +7190,7 @@ public enum KMeansPlusPlusTrainerInitAlgorithm } - /// - /// K-means is a popular clustering algorithm. With K-means, the data is clustered into a specified number of clusters in order to minimize the within-cluster sum of squares. K-means++ improves upon K-means by using a better method for choosing the initial cluster centers. - /// - /// - /// K-means++ improves upon K-means by using the Yinyang K-Means method for choosing the initial cluster centers. - /// YYK-Means accelerates K-Means up to an order of magnitude while producing exactly the same clustering results (modulo floating point precision issues). - /// YYK-Means observes that there is a lot of redundancy across iterations in the KMeans algorithms and most points do not change their clusters during an iteration. - /// It uses various bounding techniques to identify this redundancy and eliminate many distance computations and optimize centroid computations. - /// K-means. - /// K-means++ - /// + /// public sealed partial class KMeansPlusPlusClusterer : Microsoft.ML.Runtime.EntryPoints.CommonInputs.IUnsupervisedTrainerWithWeight, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInput, Microsoft.ML.ILearningPipelineItem { @@ -7474,11 +7306,7 @@ public enum LightGbmArgumentsEvalMetricType } - /// - /// Train a LightGBM binary classification model. - /// - /// Light GBM is an open source implementation of boosted trees. - /// GitHub: LightGBM + /// public sealed partial class LightGbmBinaryClassifier : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithGroupId, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithWeight, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithLabel, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInput, Microsoft.ML.ILearningPipelineItem { @@ -7681,11 +7509,7 @@ public LightGbmBinaryClassifierPipelineStep(Output output) namespace Trainers { - /// - /// Train a LightGBM multi class model. - /// - /// Light GBM is an open source implementation of boosted trees. - /// GitHub: LightGBM + /// public sealed partial class LightGbmClassifier : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithGroupId, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithWeight, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithLabel, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInput, Microsoft.ML.ILearningPipelineItem { @@ -7888,11 +7712,7 @@ public LightGbmClassifierPipelineStep(Output output) namespace Trainers { - /// - /// Train a LightGBM ranking model. - /// - /// Light GBM is an open source implementation of boosted trees. - /// GitHub: LightGBM + /// public sealed partial class LightGbmRanker : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithGroupId, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithWeight, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithLabel, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInput, Microsoft.ML.ILearningPipelineItem { @@ -8095,11 +7915,7 @@ public LightGbmRankerPipelineStep(Output output) namespace Trainers { - /// - /// LightGBM Regression - /// - /// Light GBM is an open source implementation of boosted trees. - /// GitHub: LightGBM + /// public sealed partial class LightGbmRegressor : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithGroupId, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithWeight, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithLabel, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInput, Microsoft.ML.ILearningPipelineItem { @@ -8437,37 +8253,8 @@ public LinearSvmBinaryClassifierPipelineStep(Output output) namespace Trainers { - /// - /// Logistic Regression is a method in statistics used to predict the probability of occurrence of an event and can be used as a classification algorithm. The algorithm predicts the probability of occurrence of an event by fitting data to a logistical function. - /// - /// - /// If the dependent variable has more than two possible values (blood type given diagnostic test results), then the logistic regression is multinomial. - /// - /// The optimization technique used for LogisticRegressionBinaryClassifier is the limited memory Broyden-Fletcher-Goldfarb-Shanno (L-BFGS). - /// Both the L-BFGS and regular BFGS algorithms use quasi-Newtonian methods to estimate the computationally intensive Hessian matrix in the equation used by Newton's method to calculate steps. - /// But the L-BFGS approximation uses only a limited amount of memory to compute the next step direction, - /// so that it is especially suited for problems with a large number of variables. - /// The MemorySize parameter specifies the number of past positions and gradients to store for use in the computation of the next step. - /// - /// - /// This learner can use elastic net regularization: a linear combination of L1 (lasso) and L2 (ridge) regularizations. - /// Regularization is a method that can render an ill-posed problem more tractable by imposing constraints that provide information to supplement the data and that prevents overfitting by penalizing models with extreme coefficient values. - /// This can improve the generalization of the model learned by selecting the optimal complexity in the bias-variance tradeoff. - /// Regularization works by adding the penalty that is associated with coefficient values to the error of the hypothesis. - /// An accurate model with extreme coefficient values would be penalized more, but a less accurate model with more conservative values would be penalized less. L1 and L2 regularization have different effects and uses that are complementary in certain respects. - /// - /// L1Weight: can be applied to sparse models, when working with high-dimensional data. - /// It pulls small weights associated features that are relatively unimportant towards 0. - /// L2Weight: is preferable for data that is not sparse. It pulls large weights towards zero. - /// - /// Adding the ridge penalty to the regularization overcomes some of lasso's limitations. It can improve its predictive accuracy, for example, when the number of predictors is greater than the sample size. If x = l1_weight and y = l2_weight, ax + by = c defines the linear span of the regularization terms. - /// The default values of x and y are both 1. - /// An agressive regularization can harm predictive capacity by excluding important variables out of the model. So choosing the optimal values for the regularization parameters is important for the performance of the logistic regression model. - /// Scalable Training of L1-Regularized Log-Linear Models. - /// Test Run - L1 and L2 Regularization for Machine Learning. - /// Wikipedia: L-BFGS. - /// Wikipedia: Logistic regression. - /// + /// + /// public sealed partial class LogisticRegressionBinaryClassifier : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithWeight, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithLabel, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInput, Microsoft.ML.ILearningPipelineItem { @@ -8615,37 +8402,8 @@ public LogisticRegressionBinaryClassifierPipelineStep(Output output) namespace Trainers { - /// - /// Logistic Regression is a method in statistics used to predict the probability of occurrence of an event and can be used as a classification algorithm. The algorithm predicts the probability of occurrence of an event by fitting data to a logistical function. - /// - /// - /// If the dependent variable has more than two possible values (blood type given diagnostic test results), then the logistic regression is multinomial. - /// - /// The optimization technique used for LogisticRegressionBinaryClassifier is the limited memory Broyden-Fletcher-Goldfarb-Shanno (L-BFGS). - /// Both the L-BFGS and regular BFGS algorithms use quasi-Newtonian methods to estimate the computationally intensive Hessian matrix in the equation used by Newton's method to calculate steps. - /// But the L-BFGS approximation uses only a limited amount of memory to compute the next step direction, - /// so that it is especially suited for problems with a large number of variables. - /// The MemorySize parameter specifies the number of past positions and gradients to store for use in the computation of the next step. - /// - /// - /// This learner can use elastic net regularization: a linear combination of L1 (lasso) and L2 (ridge) regularizations. - /// Regularization is a method that can render an ill-posed problem more tractable by imposing constraints that provide information to supplement the data and that prevents overfitting by penalizing models with extreme coefficient values. - /// This can improve the generalization of the model learned by selecting the optimal complexity in the bias-variance tradeoff. - /// Regularization works by adding the penalty that is associated with coefficient values to the error of the hypothesis. - /// An accurate model with extreme coefficient values would be penalized more, but a less accurate model with more conservative values would be penalized less. L1 and L2 regularization have different effects and uses that are complementary in certain respects. - /// - /// L1Weight: can be applied to sparse models, when working with high-dimensional data. - /// It pulls small weights associated features that are relatively unimportant towards 0. - /// L2Weight: is preferable for data that is not sparse. It pulls large weights towards zero. - /// - /// Adding the ridge penalty to the regularization overcomes some of lasso's limitations. It can improve its predictive accuracy, for example, when the number of predictors is greater than the sample size. If x = l1_weight and y = l2_weight, ax + by = c defines the linear span of the regularization terms. - /// The default values of x and y are both 1. - /// An agressive regularization can harm predictive capacity by excluding important variables out of the model. So choosing the optimal values for the regularization parameters is important for the performance of the logistic regression model. - /// Scalable Training of L1-Regularized Log-Linear Models. - /// Test Run - L1 and L2 Regularization for Machine Learning. - /// Wikipedia: L-BFGS. - /// Wikipedia: Logistic regression. - /// + /// + /// public sealed partial class LogisticRegressionClassifier : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithWeight, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithLabel, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInput, Microsoft.ML.ILearningPipelineItem { @@ -8866,14 +8624,7 @@ public NaiveBayesClassifierPipelineStep(Output output) namespace Trainers { - /// - /// Train a Online gradient descent perceptron. - /// - /// - /// Stochastic gradient descent uses a simple yet efficient iterative technique to fit model coefficients using error gradients for convex loss functions. - /// The OnlineGradientDescentRegressor implements the standard (non-batch) SGD, with a choice of loss functions, - /// and an option to update the weight vector using the average of the vectors seen over time (averaged argument is set to True by default). - /// + /// public sealed partial class OnlineGradientDescentRegressor : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithLabel, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInput, Microsoft.ML.ILearningPipelineItem { @@ -9026,17 +8777,7 @@ public OnlineGradientDescentRegressorPipelineStep(Output output) namespace Trainers { - /// - /// Train an PCA Anomaly model. - /// - /// - /// Principle Component Analysis (PCA) is a dimensionality-reduction transform which computes the projection of the feature vector to onto a low-rank subspace. - /// Its training is done using the technique described in the paper: Combining Structured and Unstructured Randomness in Large Scale PCA, - /// and the paper Finding Structure with Randomness: Probabilistic Algorithms for Constructing Approximate Matrix Decompositions - /// Randomized Methods for Computing the Singular Value Decomposition (SVD) of very large matrices - /// A randomized algorithm for principal component analysis - /// Finding Structure with Randomness: Probabilistic Algorithms for Constructing Approximate Matrix Decompositions - /// + /// public sealed partial class PcaAnomalyDetector : Microsoft.ML.Runtime.EntryPoints.CommonInputs.IUnsupervisedTrainerWithWeight, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInput, Microsoft.ML.ILearningPipelineItem { @@ -9130,9 +8871,7 @@ public PcaAnomalyDetectorPipelineStep(Output output) namespace Trainers { - /// - /// Train an Poisson regression model. - /// + /// public sealed partial class PoissonRegressor : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithWeight, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithLabel, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInput, Microsoft.ML.ILearningPipelineItem { @@ -9275,28 +9014,7 @@ public PoissonRegressorPipelineStep(Output output) namespace Trainers { - /// - /// Train an SDCA binary model. - /// - /// - /// This classifier is a trainer based on the Stochastic DualCoordinate Ascent(SDCA) method, a state-of-the-art optimization technique for convex objective functions. - /// The algorithm can be scaled for use on large out-of-memory data sets due to a semi-asynchronized implementation - /// that supports multi-threading. - /// - /// Convergence is underwritten by periodically enforcing synchronization between primal and dual updates in a separate thread. - /// Several choices of loss functions are also provided. - /// The SDCA method combines several of the best properties and capabilities of logistic regression and SVM algorithms. - /// - /// - /// Note that SDCA is a stochastic and streaming optimization algorithm. - /// The results depends on the order of the training data. For reproducible results, it is recommended that one sets to - /// False and to 1. - /// Elastic net regularization can be specified by the and parameters. Note that the has an effect on the rate of convergence. - /// In general, the larger the , the faster SDCA converges. - /// - /// Scaling Up Stochastic Dual Coordinate Ascent. - /// Stochastic Dual Coordinate Ascent Methods for Regularized Loss Minimization. - /// + /// public sealed partial class StochasticDualCoordinateAscentBinaryClassifier : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithLabel, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInput, Microsoft.ML.ILearningPipelineItem { @@ -9435,28 +9153,7 @@ public StochasticDualCoordinateAscentBinaryClassifierPipelineStep(Output output) namespace Trainers { - /// - /// The SDCA linear multi-class classification trainer. - /// - /// - /// This classifier is a trainer based on the Stochastic DualCoordinate Ascent(SDCA) method, a state-of-the-art optimization technique for convex objective functions. - /// The algorithm can be scaled for use on large out-of-memory data sets due to a semi-asynchronized implementation - /// that supports multi-threading. - /// - /// Convergence is underwritten by periodically enforcing synchronization between primal and dual updates in a separate thread. - /// Several choices of loss functions are also provided. - /// The SDCA method combines several of the best properties and capabilities of logistic regression and SVM algorithms. - /// - /// - /// Note that SDCA is a stochastic and streaming optimization algorithm. - /// The results depends on the order of the training data. For reproducible results, it is recommended that one sets to - /// False and to 1. - /// Elastic net regularization can be specified by the and parameters. Note that the has an effect on the rate of convergence. - /// In general, the larger the , the faster SDCA converges. - /// - /// Scaling Up Stochastic Dual Coordinate Ascent. - /// Stochastic Dual Coordinate Ascent Methods for Regularized Loss Minimization. - /// + /// public sealed partial class StochasticDualCoordinateAscentClassifier : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithLabel, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInput, Microsoft.ML.ILearningPipelineItem { @@ -9579,28 +9276,7 @@ public StochasticDualCoordinateAscentClassifierPipelineStep(Output output) namespace Trainers { - /// - /// The SDCA linear regression trainer. - /// - /// - /// This classifier is a trainer based on the Stochastic DualCoordinate Ascent(SDCA) method, a state-of-the-art optimization technique for convex objective functions. - /// The algorithm can be scaled for use on large out-of-memory data sets due to a semi-asynchronized implementation - /// that supports multi-threading. - /// - /// Convergence is underwritten by periodically enforcing synchronization between primal and dual updates in a separate thread. - /// Several choices of loss functions are also provided. - /// The SDCA method combines several of the best properties and capabilities of logistic regression and SVM algorithms. - /// - /// - /// Note that SDCA is a stochastic and streaming optimization algorithm. - /// The results depends on the order of the training data. For reproducible results, it is recommended that one sets to - /// False and to 1. - /// Elastic net regularization can be specified by the and parameters. Note that the has an effect on the rate of convergence. - /// In general, the larger the , the faster SDCA converges. - /// - /// Scaling Up Stochastic Dual Coordinate Ascent. - /// Stochastic Dual Coordinate Ascent Methods for Regularized Loss Minimization. - /// + /// public sealed partial class StochasticDualCoordinateAscentRegressor : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithLabel, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInput, Microsoft.ML.ILearningPipelineItem { @@ -10203,9 +9879,7 @@ public sealed partial class CategoricalHashTransformColumn : OneToOneColumn - /// Encodes the categorical variable with hash-based encoding - /// + /// public sealed partial class CategoricalHashOneHotVectorizer : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITransformInput, Microsoft.ML.ILearningPipelineItem { @@ -10378,9 +10052,7 @@ public sealed partial class CategoricalTransformColumn : OneToOneColumn - /// Encodes the categorical variable with one-hot encoding based on term dictionary - /// + /// public sealed partial class CategoricalOneHotVectorizer : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITransformInput, Microsoft.ML.ILearningPipelineItem { @@ -14311,9 +13983,7 @@ public sealed partial class PcaTransformColumn : OneToOneColumn - /// Train an PCA Anomaly model. - /// + /// public sealed partial class PcaCalculator : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITransformInput, Microsoft.ML.ILearningPipelineItem { diff --git a/src/Microsoft.ML/Runtime/Internal/Tools/CSharpApiGenerator.cs b/src/Microsoft.ML/Runtime/Internal/Tools/CSharpApiGenerator.cs index 29884fe620..ba130c96e3 100644 --- a/src/Microsoft.ML/Runtime/Internal/Tools/CSharpApiGenerator.cs +++ b/src/Microsoft.ML/Runtime/Internal/Tools/CSharpApiGenerator.cs @@ -382,7 +382,7 @@ private void GenerateInput(IndentingTextWriter writer, ModuleCatalog.EntryPointI GenerateEnums(writer, entryPointInfo.InputType, _defaultNamespace + entryPointMetadata.Namespace); writer.WriteLine(); GenerateClasses(writer, entryPointInfo.InputType, catalog, _defaultNamespace + entryPointMetadata.Namespace); - CSharpGeneratorUtils.GenerateSummary(writer, entryPointInfo.Description, entryPointInfo.Remarks); + CSharpGeneratorUtils.GenerateSummary(writer, entryPointInfo.Description, entryPointInfo.XmlInclude); if (entryPointInfo.ObsoleteAttribute != null) writer.WriteLine($"[Obsolete(\"{entryPointInfo.ObsoleteAttribute.Message}\")]"); diff --git a/src/Microsoft.ML/Runtime/Internal/Tools/CSharpGeneratorUtils.cs b/src/Microsoft.ML/Runtime/Internal/Tools/CSharpGeneratorUtils.cs index 1cab5cc35c..09dea02cc2 100644 --- a/src/Microsoft.ML/Runtime/Internal/Tools/CSharpGeneratorUtils.cs +++ b/src/Microsoft.ML/Runtime/Internal/Tools/CSharpGeneratorUtils.cs @@ -349,18 +349,23 @@ public static string GetComponentName(ModuleCatalog.ComponentInfo component) return $"{Capitalize(component.Name)}{component.Kind}"; } - public static void GenerateSummary(IndentingTextWriter writer, string summary, string remarks = null) + public static void GenerateSummary(IndentingTextWriter writer, string summary, string[] xmlInclude = null) { + // if the class has an XML it should contain the summary and everything else + if (xmlInclude != null) + { + foreach (var line in xmlInclude) + writer.WriteLine($"/// {line}"); + + return; + } + if (string.IsNullOrEmpty(summary)) return; writer.WriteLine("/// "); foreach (var line in summary.Split(new[] { Environment.NewLine }, StringSplitOptions.RemoveEmptyEntries)) writer.WriteLine($"/// {line}"); writer.WriteLine("/// "); - - if(!string.IsNullOrEmpty(remarks)) - foreach (var line in remarks.Split(new[] { Environment.NewLine }, StringSplitOptions.None)) - writer.WriteLine($"/// {line}"); } public static void GenerateHeader(IndentingTextWriter writer) diff --git a/test/BaselineOutput/Common/EntryPoints/core_ep-list.tsv b/test/BaselineOutput/Common/EntryPoints/core_ep-list.tsv index 9d250f4c7d..644318c05a 100644 --- a/test/BaselineOutput/Common/EntryPoints/core_ep-list.tsv +++ b/test/BaselineOutput/Common/EntryPoints/core_ep-list.tsv @@ -68,8 +68,8 @@ Trainers.StochasticGradientDescentBinaryClassifier Train an Hogwild SGD binary m Transforms.ApproximateBootstrapSampler Approximate bootstrap sampling. Microsoft.ML.Runtime.Data.BootstrapSample GetSample Microsoft.ML.Runtime.Data.BootstrapSampleTransform+Arguments Microsoft.ML.Runtime.EntryPoints.CommonOutputs+TransformOutput Transforms.BinaryPredictionScoreColumnsRenamer For binary prediction, it renames the PredictedLabel and Score columns to include the name of the positive class. Microsoft.ML.Runtime.EntryPoints.ScoreModel RenameBinaryPredictionScoreColumns Microsoft.ML.Runtime.EntryPoints.ScoreModel+RenameBinaryPredictionScoreColumnsInput Microsoft.ML.Runtime.EntryPoints.CommonOutputs+TransformOutput Transforms.BinNormalizer The values are assigned into equidensity bins and a value is mapped to its bin_number/number_of_bins. Microsoft.ML.Runtime.Data.Normalize Bin Microsoft.ML.Runtime.Data.NormalizeTransform+BinArguments Microsoft.ML.Runtime.EntryPoints.CommonOutputs+TransformOutput -Transforms.CategoricalHashOneHotVectorizer Encodes the categorical variable with hash-based encoding Microsoft.ML.Runtime.Data.Categorical CatTransformHash Microsoft.ML.Runtime.Data.CategoricalHashTransform+Arguments Microsoft.ML.Runtime.EntryPoints.CommonOutputs+TransformOutput -Transforms.CategoricalOneHotVectorizer Encodes the categorical variable with one-hot encoding based on term dictionary Microsoft.ML.Runtime.Data.Categorical CatTransformDict Microsoft.ML.Runtime.Data.CategoricalTransform+Arguments Microsoft.ML.Runtime.EntryPoints.CommonOutputs+TransformOutput +Transforms.CategoricalHashOneHotVectorizer Converts the categorical value into an indicator array by hashing the value and using the hash as an index in the bag. If the input column is a vector, a single indicator bag is returned for it. Microsoft.ML.Runtime.Data.Categorical CatTransformHash Microsoft.ML.Runtime.Data.CategoricalHashTransform+Arguments Microsoft.ML.Runtime.EntryPoints.CommonOutputs+TransformOutput +Transforms.CategoricalOneHotVectorizer Converts the categorical value into an indicator array by building a dictionary of categories based on the data and using the id in the dictionary as the index in the array. Microsoft.ML.Runtime.Data.Categorical CatTransformDict Microsoft.ML.Runtime.Data.CategoricalTransform+Arguments Microsoft.ML.Runtime.EntryPoints.CommonOutputs+TransformOutput Transforms.CharacterTokenizer Character-oriented tokenizer where text is considered a sequence of characters. Microsoft.ML.Runtime.Transforms.TextAnalytics CharTokenize Microsoft.ML.Runtime.TextAnalytics.CharTokenizeTransform+Arguments Microsoft.ML.Runtime.EntryPoints.CommonOutputs+TransformOutput Transforms.ColumnConcatenator Concatenates one or more columns of the same item type. Microsoft.ML.Runtime.EntryPoints.SchemaManipulation ConcatColumns Microsoft.ML.Runtime.Data.ConcatTransform+Arguments Microsoft.ML.Runtime.EntryPoints.CommonOutputs+TransformOutput Transforms.ColumnCopier Duplicates columns from the dataset Microsoft.ML.Runtime.EntryPoints.SchemaManipulation CopyColumns Microsoft.ML.Runtime.Data.CopyColumnsTransform+Arguments Microsoft.ML.Runtime.EntryPoints.CommonOutputs+TransformOutput @@ -106,7 +106,7 @@ Transforms.ModelCombiner Combines a sequence of TransformModels into a single mo Transforms.NGramTranslator Produces a bag of counts of ngrams (sequences of consecutive values of length 1-n) in a given vector of keys. It does so by building a dictionary of ngrams and using the id in the dictionary as the index in the bag. Microsoft.ML.Runtime.Transforms.TextAnalytics NGramTransform Microsoft.ML.Runtime.Data.NgramTransform+Arguments Microsoft.ML.Runtime.EntryPoints.CommonOutputs+TransformOutput Transforms.NoOperation Does nothing. Microsoft.ML.Runtime.Data.NopTransform Nop Microsoft.ML.Runtime.Data.NopTransform+NopInput Microsoft.ML.Runtime.EntryPoints.CommonOutputs+TransformOutput Transforms.OptionalColumnCreator If the source column does not exist after deserialization, create a column with the right type and default values. Microsoft.ML.Runtime.DataPipe.OptionalColumnTransform MakeOptional Microsoft.ML.Runtime.DataPipe.OptionalColumnTransform+Arguments Microsoft.ML.Runtime.EntryPoints.CommonOutputs+TransformOutput -Transforms.PcaCalculator Train an PCA Anomaly model. Microsoft.ML.Runtime.Data.PcaTransform Calculate Microsoft.ML.Runtime.Data.PcaTransform+Arguments Microsoft.ML.Runtime.EntryPoints.CommonOutputs+TransformOutput +Transforms.PcaCalculator PCA is a dimensionality-reduction transform which computes the projection of a numeric vector onto a low-rank subspace. Microsoft.ML.Runtime.Data.PcaTransform Calculate Microsoft.ML.Runtime.Data.PcaTransform+Arguments Microsoft.ML.Runtime.EntryPoints.CommonOutputs+TransformOutput Transforms.PredictedLabelColumnOriginalValueConverter Transforms a predicted label column to its original values, unless it is of type bool. Microsoft.ML.Runtime.EntryPoints.FeatureCombiner ConvertPredictedLabel Microsoft.ML.Runtime.EntryPoints.FeatureCombiner+PredictedLabelInput Microsoft.ML.Runtime.EntryPoints.CommonOutputs+TransformOutput Transforms.RandomNumberGenerator Adds a column with a generated number sequence. Microsoft.ML.Runtime.Data.RandomNumberGenerator Generate Microsoft.ML.Runtime.Data.GenerateNumberTransform+Arguments Microsoft.ML.Runtime.EntryPoints.CommonOutputs+TransformOutput Transforms.RowRangeFilter Filters a dataview on a column of type Single, Double or Key (contiguous). Keeps the values that are in the specified min/max range. NaNs are always filtered out. If the input is a Key type, the min/max are considered percentages of the number of values. Microsoft.ML.Runtime.EntryPoints.SelectRows FilterByRange Microsoft.ML.Runtime.Data.RangeFilter+Arguments Microsoft.ML.Runtime.EntryPoints.CommonOutputs+TransformOutput diff --git a/test/BaselineOutput/Common/EntryPoints/core_manifest.json b/test/BaselineOutput/Common/EntryPoints/core_manifest.json index 9b095d83ea..ed80555eb1 100644 --- a/test/BaselineOutput/Common/EntryPoints/core_manifest.json +++ b/test/BaselineOutput/Common/EntryPoints/core_manifest.json @@ -15823,7 +15823,7 @@ }, { "Name": "Transforms.CategoricalHashOneHotVectorizer", - "Desc": "Encodes the categorical variable with hash-based encoding", + "Desc": "Converts the categorical value into an indicator array by hashing the value and using the hash as an index in the bag. If the input column is a vector, a single indicator bag is returned for it.", "FriendlyName": "Categorical Hash Transform", "ShortName": null, "Inputs": [ @@ -16029,7 +16029,7 @@ }, { "Name": "Transforms.CategoricalOneHotVectorizer", - "Desc": "Encodes the categorical variable with one-hot encoding based on term dictionary", + "Desc": "Converts the categorical value into an indicator array by building a dictionary of categories based on the data and using the id in the dictionary as the index in the array.", "FriendlyName": "Categorical Transform", "ShortName": null, "Inputs": [ @@ -19779,7 +19779,7 @@ }, { "Name": "Transforms.PcaCalculator", - "Desc": "Train an PCA Anomaly model.", + "Desc": "PCA is a dimensionality-reduction transform which computes the projection of a numeric vector onto a low-rank subspace.", "FriendlyName": "Principal Component Analysis Transform", "ShortName": "Pca", "Inputs": [