diff --git a/src/Microsoft.ML.Core/Utilities/ReservoirSampler.cs b/src/Microsoft.ML.Core/Utilities/ReservoirSampler.cs index a755788fb4..b8006bd943 100644 --- a/src/Microsoft.ML.Core/Utilities/ReservoirSampler.cs +++ b/src/Microsoft.ML.Core/Utilities/ReservoirSampler.cs @@ -47,7 +47,7 @@ public interface IReservoirSampler /// This class produces a sample without replacement from a stream of data of type . /// It is instantiated with a delegate that gets the next data point, and builds a reservoir in one pass by calling /// for every data point in the stream. In case the next data point does not get 'picked' into the reservoir, the delegate is not invoked. - /// Sampling is done according to the algorithm in this paper: . + /// Sampling is done according to the algorithm in this paper: http://epubs.siam.org/doi/pdf/10.1137/1.9781611972740.53. /// public sealed class ReservoirSamplerWithoutReplacement : IReservoirSampler { @@ -120,7 +120,7 @@ public IEnumerable GetSample() /// This class produces a sample with replacement from a stream of data of type . /// It is instantiated with a delegate that gets the next data point, and builds a reservoir in one pass by calling /// for every data point in the stream. In case the next data point does not get 'picked' into the reservoir, the delegate is not invoked. - /// Sampling is done according to the algorithm in this paper: . + /// Sampling is done according to the algorithm in this paper: http://epubs.siam.org/doi/pdf/10.1137/1.9781611972740.53. /// public sealed class ReservoirSamplerWithReplacement : IReservoirSampler { diff --git a/src/Microsoft.ML.Data/Evaluators/AucAggregator.cs b/src/Microsoft.ML.Data/Evaluators/AucAggregator.cs index f45aacd58e..342e1d3529 100644 --- a/src/Microsoft.ML.Data/Evaluators/AucAggregator.cs +++ b/src/Microsoft.ML.Data/Evaluators/AucAggregator.cs @@ -408,7 +408,7 @@ public UnweightedAuPrcAggregator(IRandom rand, int reservoirSize) /// /// Compute the AUPRC using the "lower trapesoid" estimator, as described in the paper - /// . + /// http://www.ecmlpkdd2013.org/wp-content/uploads/2013/07/aucpr_2013ecml_corrected.pdf. /// protected override Double ComputeWeightedAuPrcCore(out Double unweighted) { @@ -482,7 +482,7 @@ public WeightedAuPrcAggregator(IRandom rand, int reservoirSize) /// /// Compute the AUPRC using the "lower trapesoid" estimator, as described in the paper - /// . + /// http://www.ecmlpkdd2013.org/wp-content/uploads/2013/07/aucpr_2013ecml_corrected.pdf. /// protected override Double ComputeWeightedAuPrcCore(out Double unweighted) { diff --git a/src/Microsoft.ML.Data/Transforms/NAFilter.cs b/src/Microsoft.ML.Data/Transforms/NAFilter.cs index 7b94ff1e07..c8515291f3 100644 --- a/src/Microsoft.ML.Data/Transforms/NAFilter.cs +++ b/src/Microsoft.ML.Data/Transforms/NAFilter.cs @@ -26,6 +26,7 @@ namespace Microsoft.ML.Runtime.Data { + /// public sealed class NAFilter : FilterBase { private static class Defaults diff --git a/src/Microsoft.ML.Data/Transforms/TermTransform.cs b/src/Microsoft.ML.Data/Transforms/TermTransform.cs index 7591179588..ea2248716e 100644 --- a/src/Microsoft.ML.Data/Transforms/TermTransform.cs +++ b/src/Microsoft.ML.Data/Transforms/TermTransform.cs @@ -29,14 +29,14 @@ namespace Microsoft.ML.Runtime.Data { - /// - /// TermTransform builds up term vocabularies (dictionaries). - /// Notes: - /// * Each column builds/uses exactly one "vocabulary" (dictionary). - /// * Output columns are KeyType-valued. - /// * The Key value is the one-based index of the item in the dictionary. - /// * Not found is assigned the value zero. - /// + + // TermTransform builds up term vocabularies (dictionaries). + // Notes: + // * Each column builds/uses exactly one "vocabulary" (dictionary). + // * Output columns are KeyType-valued. + // * The Key value is the one-based index of the item in the dictionary. + // * Not found is assigned the value zero. + /// public sealed partial class TermTransform : OneToOneTransformBase, ITransformTemplate { public abstract class ColumnBase : OneToOneColumn diff --git a/src/Microsoft.ML.Data/Transforms/doc.xml b/src/Microsoft.ML.Data/Transforms/doc.xml new file mode 100644 index 0000000000..a3d4ba9f5e --- /dev/null +++ b/src/Microsoft.ML.Data/Transforms/doc.xml @@ -0,0 +1,54 @@ + + + + + + Removes missing values from vector type columns. + + + This transform removes the entire row if any of the input columns have a missing value in that row. + This preprocessing is required for many ML algorithms that cannot work with missing values. + Useful if any missing entry invalidates the entire row. + If the is set to true, this transform would do the exact opposite, + it will keep only the rows that have missing values. + + + + + + + pipeline.Add(new MissingValuesRowDropper("Column1")); + + + + + + + Converts input values (words, numbers, etc.) to index in a dictionary. + + + The TextToKeyConverter transform builds up term vocabularies (dictionaries). + The TextToKey Converter and the are the two one primary mechanisms by which raw input is transformed into keys. + If multiple columns are used, each column builds/uses exactly one vocabulary. + The output columns are KeyType-valued. + The Key value is the one-based index of the item in the dictionary. + If the key is not found in the dictionary, it is assigned the missing value indicator. + This dictionary mapping values to keys is most commonly learnt from the unique values in input data, + but can be defined through other means: either with the mapping defined directly on the command line, or as loaded from an external file. + + + + + + + + pipeline.Add(new TextToKeyConverter(("Column", "OutColumn")) + { + Sort = TermTransformSortOrder.Occurrence + }); + + + + + + diff --git a/src/Microsoft.ML.FastTree/FastTreeArguments.cs b/src/Microsoft.ML.FastTree/FastTreeArguments.cs index e6274e3155..2c6fc02745 100644 --- a/src/Microsoft.ML.FastTree/FastTreeArguments.cs +++ b/src/Microsoft.ML.FastTree/FastTreeArguments.cs @@ -20,7 +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 4eca3e15fb..ac92867c27 100644 --- a/src/Microsoft.ML.FastTree/FastTreeClassification.cs +++ b/src/Microsoft.ML.FastTree/FastTreeClassification.cs @@ -100,7 +100,7 @@ public static IPredictorProducing Create(IHostEnvironment env, ModelLoadC public override PredictionKind PredictionKind => PredictionKind.BinaryClassification; } - /// + /// public sealed partial class FastTreeBinaryClassificationTrainer : BoostingFastTreeTrainerBase> { @@ -342,7 +342,8 @@ public static partial class FastTree Desc = FastTreeBinaryClassificationTrainer.Summary, UserName = FastTreeBinaryClassificationTrainer.UserNameValue, ShortName = FastTreeBinaryClassificationTrainer.ShortName, - XmlInclude = new[] { @"" })] + 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 0e44553dee..cc246f25cd 100644 --- a/src/Microsoft.ML.FastTree/FastTreeRanking.cs +++ b/src/Microsoft.ML.FastTree/FastTreeRanking.cs @@ -38,7 +38,7 @@ namespace Microsoft.ML.Runtime.FastTree { - /// + /// public sealed partial class FastTreeRankingTrainer : BoostingFastTreeTrainerBase, IHasLabelGains { @@ -1096,7 +1096,8 @@ public static partial class FastTree Desc = FastTreeRankingTrainer.Summary, UserName = FastTreeRankingTrainer.UserNameValue, ShortName = FastTreeRankingTrainer.ShortName, - XmlInclude = new[] { @"" })] + 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 1e78f4c473..287cfe9e1c 100644 --- a/src/Microsoft.ML.FastTree/FastTreeRegression.cs +++ b/src/Microsoft.ML.FastTree/FastTreeRegression.cs @@ -31,7 +31,7 @@ namespace Microsoft.ML.Runtime.FastTree { - /// + /// public sealed partial class FastTreeRegressionTrainer : BoostingFastTreeTrainerBase { public const string LoadNameValue = "FastTreeRegression"; @@ -445,7 +445,8 @@ public static partial class FastTree Desc = FastTreeRegressionTrainer.Summary, UserName = FastTreeRegressionTrainer.UserNameValue, ShortName = FastTreeRegressionTrainer.ShortName, - XmlInclude = new[] { @"" })] + 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 6c1b56b1eb..d02928884f 100644 --- a/src/Microsoft.ML.FastTree/FastTreeTweedie.cs +++ b/src/Microsoft.ML.FastTree/FastTreeTweedie.cs @@ -30,7 +30,7 @@ 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 - /// + /// public sealed partial class FastTreeTweedieTrainer : BoostingFastTreeTrainerBase { public const string LoadNameValue = "FastTreeTweedieRegression"; @@ -454,7 +454,7 @@ public static partial class FastTree Desc = FastTreeTweedieTrainer.Summary, UserName = FastTreeTweedieTrainer.UserNameValue, ShortName = FastTreeTweedieTrainer.ShortName, - XmlInclude = new [] { @"" })] + XmlInclude = new [] { @"" })] public static CommonOutputs.RegressionOutput TrainTweedieRegression(IHostEnvironment env, FastTreeTweedieTrainer.Arguments input) { Contracts.CheckValue(env, nameof(env)); diff --git a/src/Microsoft.ML.FastTree/RandomForestClassification.cs b/src/Microsoft.ML.FastTree/RandomForestClassification.cs index 612313fb93..512e79faf9 100644 --- a/src/Microsoft.ML.FastTree/RandomForestClassification.cs +++ b/src/Microsoft.ML.FastTree/RandomForestClassification.cs @@ -106,7 +106,7 @@ public static IPredictorProducing Create(IHostEnvironment env, ModelLoadC } } - /// + /// public sealed partial class FastForestClassification : RandomForestTrainerBase> { @@ -206,7 +206,8 @@ public static partial class FastForest Desc = FastForestClassification.Summary, UserName = FastForestClassification.UserNameValue, ShortName = FastForestClassification.ShortName, - XmlInclude = new[] { @"" })] + 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 7c45af3e54..c580851534 100644 --- a/src/Microsoft.ML.FastTree/RandomForestRegression.cs +++ b/src/Microsoft.ML.FastTree/RandomForestRegression.cs @@ -137,7 +137,7 @@ public ISchemaBindableMapper CreateMapper(Double[] quantiles) } } - /// + /// public sealed partial class FastForestRegression : RandomForestTrainerBase { public sealed class Arguments : FastForestArgumentsBase @@ -277,7 +277,8 @@ public static partial class FastForest Desc = FastForestRegression.Summary, UserName = FastForestRegression.LoadNameValue, ShortName = FastForestRegression.ShortName, - XmlInclude = new[] { @"" })] + XmlInclude = new[] { @"", + @""})] public static CommonOutputs.RegressionOutput TrainRegression(IHostEnvironment env, FastForestRegression.Arguments input) { Contracts.CheckValue(env, nameof(env)); diff --git a/src/Microsoft.ML.FastTree/Training/Parallel/IParallelTraining.cs b/src/Microsoft.ML.FastTree/Training/Parallel/IParallelTraining.cs index 525e60947b..08ae6fb16f 100644 --- a/src/Microsoft.ML.FastTree/Training/Parallel/IParallelTraining.cs +++ b/src/Microsoft.ML.FastTree/Training/Parallel/IParallelTraining.cs @@ -33,20 +33,20 @@ public delegate void FindBestThresholdFromRawArrayFun(LeafSplitCandidates leafSp /// /// Interface used for parallel training. /// Mainly contains three parts: - /// 1. interactive with IO: , . + /// 1. interactive with IO: , . /// Data will be partitioned by rows in Data parallel and Voting Parallel. /// To speed up the find bin process, it let different workers to find bins for different features. /// Then perform global sync up. /// In Feature parallel, every machines holds all data, so this is unneeded. - /// 2. interactive with TreeLearner: , , , - /// , , , . + /// 2. interactive with TreeLearner: , , , + /// , , , . /// A full process is: - /// Use to alter local active features. - /// Use to check smaller leaf and larger leaf. - /// Use , and to interactive with Feature histograms. - /// Use to sync up global best split - /// Use to record global num_data in leaves. - /// 3. interactive with Application : . + /// Use to alter local active features. + /// Use to check smaller leaf and larger leaf. + /// Use , and to interactive with Feature histograms. + /// Use to sync up global best split + /// Use to record global num_data in leaves. + /// 3. interactive with Application : . /// Output of leaves is calculated by newton step ( - sum(first_order_gradients) / sum(second_order_gradients)). /// If data is partitioned by row, it needs to a sync up for these sum result. /// So It needs to call this to get the real output of leaves. diff --git a/src/Microsoft.ML.FastTree/TreeEnsembleFeaturizer.cs b/src/Microsoft.ML.FastTree/TreeEnsembleFeaturizer.cs index a7044d2502..577b012815 100644 --- a/src/Microsoft.ML.FastTree/TreeEnsembleFeaturizer.cs +++ b/src/Microsoft.ML.FastTree/TreeEnsembleFeaturizer.cs @@ -544,6 +544,7 @@ public ISchemaBoundMapper Bind(IHostEnvironment env, RoleMappedSchema schema) } } + /// public static class TreeEnsembleFeaturizerTransform { public sealed class Arguments : TrainAndScoreTransform.ArgumentsBase @@ -802,7 +803,11 @@ private static IDataView AppendLabelTransform(IHostEnvironment env, IChannel ch, public static partial class TreeFeaturize { - [TlcModule.EntryPoint(Name = "Transforms.TreeLeafFeaturizer", Desc = TreeEnsembleFeaturizerTransform.TreeEnsembleSummary, UserName = TreeEnsembleFeaturizerTransform.UserName, ShortName = TreeEnsembleFeaturizerBindableMapper.LoadNameShort)] + [TlcModule.EntryPoint(Name = "Transforms.TreeLeafFeaturizer", + Desc = TreeEnsembleFeaturizerTransform.TreeEnsembleSummary, + UserName = TreeEnsembleFeaturizerTransform.UserName, + ShortName = TreeEnsembleFeaturizerBindableMapper.LoadNameShort, + XmlInclude = new[] { @"" })] public static CommonOutputs.TransformOutput Featurizer(IHostEnvironment env, TreeEnsembleFeaturizerTransform.ArgumentsForEntryPoint input) { Contracts.CheckValue(env, nameof(env)); diff --git a/src/Microsoft.ML.FastTree/doc.xml b/src/Microsoft.ML.FastTree/doc.xml index 36f0b41f24..8678654182 100644 --- a/src/Microsoft.ML.FastTree/doc.xml +++ b/src/Microsoft.ML.FastTree/doc.xml @@ -1,5 +1,5 @@  - + @@ -24,14 +24,54 @@ 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. + 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.. - + For more information see: + + Wikipedia: Gradient boosting (Gradient tree boosting). + Greedy function approximation: A gradient boosting machine. + + + + + + new FastTreeRanker + { + SortingAlgorithm = "DescendingReverse", + OptimizationAlgorithm = BoostedTreeArgsOptimizationAlgorithmType.AcceleratedGradientDescent + } + + + + + + + new FastTreeRegressor + { + NumTrees = 200, + EarlyStoppingRule = new GLEarlyStoppingCriterion(), + LearningRates = 0.4f, + DropoutRate = 0.05f + } + + + + + + + new FastTreeBinaryClassifier + { + NumTrees = 100, + EarlyStoppingRule = new PQEarlyStoppingCriterion(), + LearningRates = 0.4f, + DropoutRate = 0.05f + } + + + @@ -48,17 +88,45 @@ They perform integrated feature selection and classification. They are resilient in the presence of noisy features. - Fast forest is a random forest implementation. + 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 + 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. + For more see: + + Wikipedia: Random forest + Quantile regression forest + From Stumps to Trees to Forests + + + + + new FastForestBinaryClassifier + { + NumTrees = 100, + NumLeaves = 50, + Calibrator = new FixedPlattCalibratorCalibratorTrainer() + } + + + + + + + new FastForestRegressor + { + NumTrees = 100, + NumLeaves = 50, + NumThreads = 5, + EntropyCoefficient = 0.3 + } + + + @@ -68,11 +136,57 @@ 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: + For an introduction to Gradient Boosting, and more information, see: Wikipedia: Gradient boosting (Gradient tree boosting) Greedy function approximation: A gradient boosting machine + + + + Trains a tree ensemble, or loads it from a file, then maps a numeric feature vector + to three outputs: + + A vector containing the individual tree outputs of the tree ensemble. + A vector indicating the leaves that the feature vector falls on in the tree ensemble. + A vector indicating the paths that the feature vector falls on in the tree ensemble. + + If a both a model file and a trainer are specified - will use the model file. If neither are specified, + will train a default FastTree model. + This can handle key labels by training a regression model towards their optionally permuted indices. + + + In machine learning​ it is a pretty common and powerful approach to utilize the already trained model in the process of defining features. + One such example would be the use of model's scores as features to downstream models. For example, we might run clustering on the original features, + and use the cluster distances as the new feature set. + Instead of consuming the model's output, we could go deeper, and extract the 'intermediate outputs' that are used to produce the final score. + There are a number of famous or popular examples of this technique: + + A deep neural net trained on the ImageNet dataset, with the last layer removed, is commonly used to compute the 'projection' of the image into the 'semantic feature space'. + It is observed that the Euclidean distance in this space often correlates with the 'semantic similarity': that is, all pictures of pizza are located close together, + and far away from pictures of kittens. + A matrix factorization and/or LDA model is also often used to extract the 'latent topics' or 'latent features' associated with users and items. + The weights of the linear model are often used as a crude indicator of 'feature importance'. At the very minimum, the 0-weight features are not needed by the model, + and there's no reason to compute them. + + Tree featurizer uses the decision tree ensembles for feature engineering in the same fashion as above. + Let's assume that we've built a tree ensemble of 100 trees with 100 leaves each (it doesn't matter whether boosting was used or not in training). + If we associate each leaf of each tree with a sequential integer, we can, for every incoming example x, + produce an indicator vector L(x), where Li(x) = 1 if the example x 'falls' into the leaf #i, and 0 otherwise. + Thus, for every example x, we produce a 10000-valued vector L, with exactly 100 1s and the rest zeroes. + This 'leaf indicator' vector can be considered the ensemble-induced 'footprint' of the example. + The 'distance' between two examples in the L-space is actually a Hamming distance, and is equal to the number of trees that do not distinguish the two examples. + We could repeat the same thought process for the non-leaf, or internal, nodes of the trees (we know that each tree has exactly 99 of them in our 100-leaf example), + and produce another indicator vector, N (size 9900), for each example, indicating the 'trajectory' of each example through each of the trees. + The distance in the combined 19900-dimensional LN-space will be equal to the number of 'decisions' in all trees that 'agree' on the given pair of examples. + The TreeLeafFeaturizer is also producing the third vector, T, which is defined as Ti(x) = output of tree #i on example x. + + + + pipeline.Add(new TreeLeafFeaturizer()) + + + - \ No newline at end of file + \ No newline at end of file diff --git a/src/Microsoft.ML.KMeansClustering/KMeansPlusPlusTrainer.cs b/src/Microsoft.ML.KMeansClustering/KMeansPlusPlusTrainer.cs index 3049e6a54c..3bab791fe1 100644 --- a/src/Microsoft.ML.KMeansClustering/KMeansPlusPlusTrainer.cs +++ b/src/Microsoft.ML.KMeansClustering/KMeansPlusPlusTrainer.cs @@ -28,7 +28,7 @@ namespace Microsoft.ML.Runtime.KMeans { - /// + /// public class KMeansPlusPlusTrainer : TrainerBase { public const string LoadNameValue = "KMeansPlusPlus"; @@ -207,7 +207,8 @@ private static int ComputeNumThreads(IHost host, int? argNumThreads) Desc = Summary, UserName = UserNameValue, ShortName = ShortName, - XmlInclude = new[] { @"" })] + 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 index affaeabf98..a1590595dc 100644 --- a/src/Microsoft.ML.KMeansClustering/doc.xml +++ b/src/Microsoft.ML.KMeansClustering/doc.xml @@ -1,5 +1,5 @@  - + @@ -13,10 +13,24 @@ 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++ + + K-means + K-means++ + + + + + new KMeansPlusPlusClusterer + { + MaxIterations = 100, + NumThreads = 5, + InitAlgorithm = KMeansPlusPlusTrainerInitAlgorithm.KMeansParallel + } + + + - \ No newline at end of file + \ No newline at end of file diff --git a/src/Microsoft.ML.LightGBM/LightGbmBinaryTrainer.cs b/src/Microsoft.ML.LightGBM/LightGbmBinaryTrainer.cs index c25b196b0e..7ce9f42b10 100644 --- a/src/Microsoft.ML.LightGBM/LightGbmBinaryTrainer.cs +++ b/src/Microsoft.ML.LightGBM/LightGbmBinaryTrainer.cs @@ -78,7 +78,7 @@ public static IPredictorProducing Create(IHostEnvironment env, ModelLoadC } } - /// + /// public sealed class LightGbmBinaryTrainer : LightGbmTrainerBase> { internal const string UserName = "LightGBM Binary Classifier"; @@ -133,7 +133,8 @@ public static partial class LightGbm Desc = LightGbmBinaryTrainer.Summary, UserName = LightGbmBinaryTrainer.UserName, ShortName = LightGbmBinaryTrainer.ShortName, - XmlInclude = new[] { @"" })] + 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 97649feb2a..0534f0d660 100644 --- a/src/Microsoft.ML.LightGBM/LightGbmMulticlassTrainer.cs +++ b/src/Microsoft.ML.LightGBM/LightGbmMulticlassTrainer.cs @@ -18,7 +18,7 @@ namespace Microsoft.ML.Runtime.LightGBM { - /// + /// public sealed class LightGbmMulticlassTrainer : LightGbmTrainerBase, OvaPredictor> { public const string Summary = "LightGBM Multi Class Classifier"; @@ -186,7 +186,8 @@ public static partial class LightGbm Desc = "Train a LightGBM multi class model.", UserName = LightGbmMulticlassTrainer.Summary, ShortName = LightGbmMulticlassTrainer.ShortName, - XmlInclude = new[] { @"" })] + 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 2f44a0ba9d..3bafb09ab3 100644 --- a/src/Microsoft.ML.LightGBM/LightGbmRankingTrainer.cs +++ b/src/Microsoft.ML.LightGBM/LightGbmRankingTrainer.cs @@ -68,7 +68,7 @@ public static LightGbmRankingPredictor Create(IHostEnvironment env, ModelLoadCon } } - /// + /// public sealed class LightGbmRankingTrainer : LightGbmTrainerBase { public const string UserName = "LightGBM Ranking"; @@ -131,7 +131,8 @@ public static partial class LightGbm Desc = "Train a LightGBM ranking model.", UserName = LightGbmRankingTrainer.UserName, ShortName = LightGbmRankingTrainer.ShortName, - XmlInclude = new[] { @"" })] + 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 db2f1f268a..f1b8850a72 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"; @@ -123,7 +123,8 @@ public static partial class LightGbm Desc = LightGbmRegressorTrainer.Summary, UserName = LightGbmRegressorTrainer.UserNameValue, ShortName = LightGbmRegressorTrainer.ShortName, - XmlInclude = new[] { @"" })] + XmlInclude = new[] { @"", + @""})] public static CommonOutputs.RegressionOutput TrainRegression(IHostEnvironment env, LightGbmArguments input) { Contracts.CheckValue(env, nameof(env)); diff --git a/src/Microsoft.ML.LightGBM/doc.xml b/src/Microsoft.ML.LightGBM/doc.xml index 4d53265ae3..1fcd38dd7a 100644 --- a/src/Microsoft.ML.LightGBM/doc.xml +++ b/src/Microsoft.ML.LightGBM/doc.xml @@ -1,5 +1,5 @@  - + @@ -11,6 +11,69 @@ GitHub: LightGBM + + + + new LightGbmBinaryClassifier + { + NumBoostRound = 200, + LearningRate = 0.5f, + NumLeaves = 32, + MinDataPerLeaf = 20 + } + + + + + + + new LightGbmClassifier + { + NumBoostRound = 200, + LearningRate = 0.5f, + NumLeaves = 32, + MinDataPerLeaf = 20 + } + + + + + + + new LightGbmRegressor + { + NumBoostRound = 100, + LearningRate = 0.5f, + NumLeaves = 32, + MinDataPerLeaf = 20, + Booster = new DartBoosterParameterFunction + { + XgboostDartMode = true, + UniformDrop = true + } + } + + + + + + + new LightGbmRanker + { + NumBoostRound = 100, + LearningRate = 0.5f, + NumLeaves = 32, + MinDataPerLeaf = 20, + Booster = new GbdtBoosterParameterFunction + { + MinSplitGain = 3, + MaxDepth = 200, + Subsample = 0.5 + } + } + + + - \ No newline at end of file + \ No newline at end of file diff --git a/src/Microsoft.ML.PCA/PcaTrainer.cs b/src/Microsoft.ML.PCA/PcaTrainer.cs index bebaa49691..f90b405c4e 100644 --- a/src/Microsoft.ML.PCA/PcaTrainer.cs +++ b/src/Microsoft.ML.PCA/PcaTrainer.cs @@ -270,7 +270,8 @@ private static void PostProcess(VBuffer[] y, Float[] sigma, Float[] z, in Desc = "Train an PCA Anomaly model.", UserName = UserNameValue, ShortName = ShortName, - XmlInclude = new[] { @"" })] + XmlInclude = new[] { @"", + @"" })] public static CommonOutputs.AnomalyDetectionOutput TrainPcaAnomaly(IHostEnvironment env, Arguments input) { Contracts.CheckValue(env, nameof(env)); @@ -290,7 +291,7 @@ public static CommonOutputs.AnomalyDetectionOutput TrainPcaAnomaly(IHostEnvironm // - - 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, diff --git a/src/Microsoft.ML.PCA/PcaTransform.cs b/src/Microsoft.ML.PCA/PcaTransform.cs index 0807abc5ed..6efbead226 100644 --- a/src/Microsoft.ML.PCA/PcaTransform.cs +++ b/src/Microsoft.ML.PCA/PcaTransform.cs @@ -26,7 +26,7 @@ namespace Microsoft.ML.Runtime.Data { - /// + /// public sealed class PcaTransform : OneToOneTransformBase { public sealed class Arguments : TransformInputBase @@ -541,7 +541,8 @@ private static void TransformFeatures(IExceptionContext ectx, ref VBuffer Desc = Summary, UserName = UserName, ShortName = ShortName, - XmlInclude = new[] { @"" })] + 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 index 98d423b754..c4f0be7758 100644 --- a/src/Microsoft.ML.PCA/doc.xml +++ b/src/Microsoft.ML.PCA/doc.xml @@ -1,27 +1,50 @@  - + - PCA is a dimensionality-reduction transform which computes the projection of the feature vector to onto a low-rank subspace. + PCA is a dimensionality-reduction transform which computes the projection of the feature vector 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. + Principle Component Analysis (PCA) is a dimensionality-reduction algorithm 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 + and the paper Finding Structure with Randomness: Probabilistic Algorithms for Constructing Approximate Matrix Decompositions + For more information, see also: + + + 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 }); - + + + + + new PcaAnomalyDetector + { + Rank = 40, + Oversampling = 40, + NormalizeFeatures = Microsoft.ML.Models.NormalizeOption.Warn + } + + + - \ No newline at end of file + \ 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 58c28b8712..62270763de 100644 --- a/src/Microsoft.ML.StandardLearners/FactorizationMachine/FactorizationMachineTrainer.cs +++ b/src/Microsoft.ML.StandardLearners/FactorizationMachine/FactorizationMachineTrainer.cs @@ -29,7 +29,7 @@ namespace Microsoft.ML.Runtime.FactorizationMachine [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 { public const string Summary = "Train a field-aware factorization machine for binary classification"; @@ -365,7 +365,8 @@ public override FieldAwareFactorizationMachinePredictor Train(TrainContext conte Desc = Summary, UserName = UserName, ShortName = ShortName, - XmlInclude = new[] { @"" })] + 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 index 2e72b2ea9f..f18bf60990 100644 --- a/src/Microsoft.ML.StandardLearners/FactorizationMachine/doc.xml +++ b/src/Microsoft.ML.StandardLearners/FactorizationMachine/doc.xml @@ -1,5 +1,5 @@  - + @@ -9,34 +9,35 @@ 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 + 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 + [1] Field-aware Factorization Machines for CTR Prediction - - [2] Adaptive Subgradient Methods for Online Learning and Stochastic Optimization - + [2] Adaptive Subgradient Methods for Online Learning and Stochastic Optimization - - [3] An Improved Stochastic Gradient Method for Training Large-scale Field-aware Factorization Machine. - + [3] An Improved Stochastic Gradient Method for Training Large-scale Field-aware Factorization Machine. + + - - pipeline.Add(new FieldAwareFactorizationMachineBinaryClassifier(){ LearningRate = 0.5f, Iter=2 }); + + pipeline.Add(new FieldAwareFactorizationMachineBinaryClassifier + { + LearningRate = 0.5f, + Iter=2 + }); - + - \ No newline at end of file + \ 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 5ae866c5d7..81b38e6976 100644 --- a/src/Microsoft.ML.StandardLearners/Standard/LinearClassificationTrainer.cs +++ b/src/Microsoft.ML.StandardLearners/Standard/LinearClassificationTrainer.cs @@ -1736,7 +1736,8 @@ public static partial class Sdca Desc = "Train an SDCA binary model.", UserName = LinearClassificationTrainer.UserNameValue, ShortName = LinearClassificationTrainer.LoadNameValue, - XmlInclude = new[] { @"" })] + 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/LogisticRegression.cs b/src/Microsoft.ML.StandardLearners/Standard/LogisticRegression/LogisticRegression.cs index f720b960a4..e896b69e1c 100644 --- a/src/Microsoft.ML.StandardLearners/Standard/LogisticRegression/LogisticRegression.cs +++ b/src/Microsoft.ML.StandardLearners/Standard/LogisticRegression/LogisticRegression.cs @@ -30,8 +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"; @@ -390,8 +390,8 @@ protected override ParameterMixingCalibratedPredictor CreatePredictor() Desc = Summary, UserName = UserNameValue, ShortName = ShortName, - XmlInclude = new[] { @"", - @""})] + XmlInclude = new[] { @"", + @""})] public static CommonOutputs.BinaryClassificationOutput TrainBinary(IHostEnvironment env, Arguments input) { diff --git a/src/Microsoft.ML.StandardLearners/Standard/LogisticRegression/MulticlassLogisticRegression.cs b/src/Microsoft.ML.StandardLearners/Standard/LogisticRegression/MulticlassLogisticRegression.cs index 5f7712843f..42cf9d690b 100644 --- a/src/Microsoft.ML.StandardLearners/Standard/LogisticRegression/MulticlassLogisticRegression.cs +++ b/src/Microsoft.ML.StandardLearners/Standard/LogisticRegression/MulticlassLogisticRegression.cs @@ -36,8 +36,8 @@ namespace Microsoft.ML.Runtime.Learners { - /// - /// + /// + /// public sealed class MulticlassLogisticRegression : LbfgsTrainerBase, MulticlassLogisticRegressionPredictor> { public const string LoadNameValue = "MultiClassLogisticRegression"; @@ -964,8 +964,8 @@ public partial class LogisticRegression Desc = Summary, UserName = MulticlassLogisticRegression.UserNameValue, ShortName = MulticlassLogisticRegression.ShortName, - XmlInclude = new[] { @"", - @"" })] + 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 index 5ac68e2fc0..03b844a0ea 100644 --- a/src/Microsoft.ML.StandardLearners/Standard/LogisticRegression/doc.xml +++ b/src/Microsoft.ML.StandardLearners/Standard/LogisticRegression/doc.xml @@ -1,40 +1,41 @@  - + - 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. + 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. + 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. + The optimization technique used for LogisticRegression Classifier is based on 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. + The MemorySize argument 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 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. + 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. - - + + 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. + L1 regularization is an implementation of OWLQN, based on: + Scalable training of L1-regularized log-linear models + + 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. @@ -50,18 +51,18 @@ - + pipeline.Add(new LogisticRegressionClassifier()); - + pipeline.Add(new LogisticRegressionBinaryClassifier()); - \ No newline at end of file + \ No newline at end of file diff --git a/src/Microsoft.ML.StandardLearners/Standard/MultiClass/MultiClassNaiveBayesTrainer.cs b/src/Microsoft.ML.StandardLearners/Standard/MultiClass/MultiClassNaiveBayesTrainer.cs index 94bac1d9ec..bb6c6101ae 100644 --- a/src/Microsoft.ML.StandardLearners/Standard/MultiClass/MultiClassNaiveBayesTrainer.cs +++ b/src/Microsoft.ML.StandardLearners/Standard/MultiClass/MultiClassNaiveBayesTrainer.cs @@ -26,18 +26,13 @@ namespace Microsoft.ML.Runtime.Learners { + /// public sealed class MultiClassNaiveBayesTrainer : TrainerBase { public const string LoadName = "MultiClassNaiveBayes"; internal const string UserName = "Multiclass Naive Bayes"; internal const string ShortName = "MNB"; internal const string Summary = "Trains a multiclass Naive Bayes predictor that supports binary feature values."; - internal const string Remarks = @" -Naive Bayes is a probabilistic classifier that can be used for multiclass problems. -Using Bayes' theorem, the conditional probability for a sample belonging to a class can be calculated based on the sample count for each feature combination groups. -However, Naive Bayes Classifier is feasible only if the number of features and the values each feature can take is relatively small. -It also assumes that the features are strictly independent. -"; public sealed class Arguments : LearnerInputBaseWithLabel { @@ -126,7 +121,10 @@ public override MultiClassNaiveBayesPredictor Train(TrainContext context) [TlcModule.EntryPoint(Name = "Trainers.NaiveBayesClassifier", Desc = "Train a MultiClassNaiveBayesTrainer.", - UserName = UserName, ShortName = ShortName)] + UserName = UserName, + ShortName = ShortName, + XmlInclude = new[] { @"", + @"" })] public static CommonOutputs.MulticlassClassificationOutput TrainMultiClassNaiveBayesTrainer(IHostEnvironment env, Arguments input) { Contracts.CheckValue(env, nameof(env)); diff --git a/src/Microsoft.ML.StandardLearners/Standard/MultiClass/Ova.cs b/src/Microsoft.ML.StandardLearners/Standard/MultiClass/Ova.cs index 62e3a79631..ed1bc17aad 100644 --- a/src/Microsoft.ML.StandardLearners/Standard/MultiClass/Ova.cs +++ b/src/Microsoft.ML.StandardLearners/Standard/MultiClass/Ova.cs @@ -36,6 +36,7 @@ namespace Microsoft.ML.Runtime.Learners using TScalarPredictor = IPredictorProducing; using TScalarTrainer = ITrainer>; + /// public sealed class Ova : MetaMulticlassTrainer { internal const string LoadNameValue = "OVA"; diff --git a/src/Microsoft.ML.StandardLearners/Standard/MultiClass/Pkpd.cs b/src/Microsoft.ML.StandardLearners/Standard/MultiClass/Pkpd.cs index 1c4700ccdd..073488f75c 100644 --- a/src/Microsoft.ML.StandardLearners/Standard/MultiClass/Pkpd.cs +++ b/src/Microsoft.ML.StandardLearners/Standard/MultiClass/Pkpd.cs @@ -31,6 +31,29 @@ namespace Microsoft.ML.Runtime.Learners using TDistPredictor = IDistPredictorProducing; using CR = RoleMappedSchema.ColumnRole; + /// + /// In this strategy, a binary classification algorithm is trained on each pair of classes. + /// The pairs are unordered but created with replacement: so, if there were three classes, 0, 1, + /// 2, we would train classifiers for the pairs (0,0), (0,1), (0,2), (1,1), (1,2), + /// and(2,2). For each binary classifier, an input data point is considered a + /// positive example if it is in either of the two classes in the pair, and a + /// negative example otherwise. At prediction time, the probabilities for each + /// pair of classes is considered as the probability of being in either class of + /// the pair given the data, and the final predictive probabilities out of that + /// per class are calculated given the probability that an example is in any given + /// pair. + /// + /// These two can allow you to exploit trainers that do not naturally have a + /// multiclass option, e.g., using the Runtime.FastTree.FastTreeBinaryClassificationTrainer + /// to solve a multiclass problem. + /// Alternately, it can allow ML.NET to solve a "simpler" problem even in the cases + /// where the trainer has a multiclass option, but using it directly is not + /// practical due to, usually, memory constraints.For example, while a multiclass + /// logistic regression is a more principled way to solve a multiclass problem, it + /// requires that the learner store a lot more intermediate state in the form of + /// L-BFGS history for all classes *simultaneously*, rather than just one-by-one + /// as would be needed for OVA. + /// public sealed class Pkpd : MetaMulticlassTrainer { internal const string LoadNameValue = "PKPD"; diff --git a/src/Microsoft.ML.StandardLearners/Standard/MultiClass/doc.xml b/src/Microsoft.ML.StandardLearners/Standard/MultiClass/doc.xml new file mode 100644 index 0000000000..8d2af374db --- /dev/null +++ b/src/Microsoft.ML.StandardLearners/Standard/MultiClass/doc.xml @@ -0,0 +1,62 @@ + + + + + + + Trains a multiclass Naive Bayes predictor that supports binary feature values. + + + Naive Bayes is a probabilistic classifier that can be used for multiclass problems. + Using Bayes' theorem, the conditional probability for a sample belonging to a class can be calculated based on the sample count for each feature combination groups. + However, Naive Bayes Classifier is feasible only if the number of features and the values each feature can take is relatively small. + It assumes independence among the presence of features in a class even though they may be dependent on each other. + This multi-class trainer accepts binary feature values of type float, i.e., feature values are either true or false. + Specifically a feature value greater than zero is treated as true. + + + + + + + + + + pipeline.Add(new NaiveBayesClassifier + { + NormalizeFeatures = NormalizeOption.Auto, + Caching = CachingOptions.Memory + }); + + + + + + + Trains a one-versus-all multi-class classifier on top of the specified binary classifier. + + + In this strategy, a binary classification algorithm is used to train one classifier for each class, which distinguishes that class from all other classes. + Prediction is then performed by running these binary classifiers, and choosing the prediction with the highest confidence score. + This algorithm can be used with any of the binary classifiers in ML.NET. + A few binary classifiers already have implementation for multi-class problems, + thus users can choose either one depending on the context. + The OVA version of a binary classifier, such as wrapping a LightGbmBinaryClassifier , + can be different from LightGbmClassifier, which develops a multi-class classifier directly. + Note that even if the classifier indicates that it does not need caching, OneVersusAll will always + request caching, as it will be performing multiple passes over the data set. + These learner will request normalization from the data pipeline if the classifier indicates it would benefit from it. + + + + + + + + pipeline.Add(OneVersusAll.With(new StochasticDualCoordinateAscentBinaryClassifier())); + + + + + + \ 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 a2e09b6905..c7c2d1d627 100644 --- a/src/Microsoft.ML.StandardLearners/Standard/Online/AveragedPerceptron.cs +++ b/src/Microsoft.ML.StandardLearners/Standard/Online/AveragedPerceptron.cs @@ -28,7 +28,7 @@ namespace Microsoft.ML.Runtime.Learners // - 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 { @@ -91,7 +91,8 @@ protected override LinearBinaryPredictor CreatePredictor() Desc = Summary, UserName = UserNameValue, ShortName = ShortName, - XmlInclude = new[] { @"" })] + 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 5cbdc01478..78dc5ea3b2 100644 --- a/src/Microsoft.ML.StandardLearners/Standard/Online/OnlineGradientDescent.cs +++ b/src/Microsoft.ML.StandardLearners/Standard/Online/OnlineGradientDescent.cs @@ -27,7 +27,7 @@ namespace Microsoft.ML.Runtime.Learners { using TPredictor = LinearRegressionPredictor; - /// + /// public sealed class OnlineGradientDescentTrainer : AveragedLinearTrainer { internal const string LoadNameValue = "OnlineGradientDescent"; @@ -89,7 +89,8 @@ protected override TPredictor CreatePredictor() Desc = "Train a Online gradient descent perceptron.", UserName = UserNameValue, ShortName = ShortName, - XmlInclude = new[] { @"" })] + 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 index 1ab7647c4f..0ace721221 100644 --- a/src/Microsoft.ML.StandardLearners/Standard/Online/doc.xml +++ b/src/Microsoft.ML.StandardLearners/Standard/Online/doc.xml @@ -1,11 +1,11 @@  - + 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. + In the ML.Net the implementation of OGD, 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. @@ -13,6 +13,18 @@ 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). + + + + new OnlineGradientDescentRegressor + { + NumIterations = 10, + L2RegularizerWeight = 0.6f, + LossFunction = new PoissonLossRegressionLossFunction() + } + + + @@ -39,6 +51,18 @@ Large Margin Classification Using the Perceptron Algorithm + + + + new AveragedPerceptronBinaryClassifier + { + NumIterations = 10, + L2RegularizerWeight = 0.01f, + LossFunction = new ExpLossClassificationLossFunction() + } + + + - \ No newline at end of file + \ 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 94dbb42325..d8bcd68c9f 100644 --- a/src/Microsoft.ML.StandardLearners/Standard/PoissonRegression/PoissonRegression.cs +++ b/src/Microsoft.ML.StandardLearners/Standard/PoissonRegression/PoissonRegression.cs @@ -26,7 +26,7 @@ namespace Microsoft.ML.Runtime.Learners { - /// + /// public sealed class PoissonRegression : LbfgsTrainerBase { internal const string LoadNameValue = "PoissonRegression"; @@ -127,7 +127,8 @@ protected override void ProcessPriorDistribution(Float label, Float weight) Desc = "Train an Poisson regression model.", UserName = UserNameValue, ShortName = ShortName, - XmlInclude = new[] { @"" })] + 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 index 4d2aeec579..ec14c9446b 100644 --- a/src/Microsoft.ML.StandardLearners/Standard/PoissonRegression/doc.xml +++ b/src/Microsoft.ML.StandardLearners/Standard/PoissonRegression/doc.xml @@ -1,5 +1,5 @@  - + @@ -12,6 +12,17 @@ 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. + + + + new PoissonRegressor + { + MaxIterations = 100, + L2Weight = 0.6f + } + + + - \ No newline at end of file + \ 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 facceffd70..0354668b31 100644 --- a/src/Microsoft.ML.StandardLearners/Standard/SdcaMultiClass.cs +++ b/src/Microsoft.ML.StandardLearners/Standard/SdcaMultiClass.cs @@ -29,7 +29,7 @@ namespace Microsoft.ML.Runtime.Learners using TVectorPredictor = IPredictorProducing>; // SDCA linear multiclass trainer. - /// + /// public class SdcaMultiClassTrainer : SdcaTrainerBase { public const string LoadNameValue = "SDCAMC"; @@ -375,7 +375,8 @@ public static partial class Sdca Desc = SdcaMultiClassTrainer.Summary, UserName = SdcaMultiClassTrainer.UserNameValue, ShortName = SdcaMultiClassTrainer.ShortName, - XmlInclude = new[] { @"" })] + 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 466625a679..bfa0796bed 100644 --- a/src/Microsoft.ML.StandardLearners/Standard/SdcaRegression.cs +++ b/src/Microsoft.ML.StandardLearners/Standard/SdcaRegression.cs @@ -25,7 +25,7 @@ namespace Microsoft.ML.Runtime.Learners { using TScalarPredictor = IPredictorWithFeatureWeights; - /// + /// public sealed class SdcaRegressionTrainer : SdcaTrainerBase { public const string LoadNameValue = "SDCAR"; @@ -127,7 +127,8 @@ public static partial class Sdca Desc = SdcaRegressionTrainer.Summary, UserName = SdcaRegressionTrainer.UserNameValue, ShortName = SdcaRegressionTrainer.ShortName, - XmlInclude = new[] { @"" })] + 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 index 0b4336a96e..a704827b88 100644 --- a/src/Microsoft.ML.StandardLearners/Standard/doc.xml +++ b/src/Microsoft.ML.StandardLearners/Standard/doc.xml @@ -1,5 +1,5 @@  - + @@ -7,7 +7,7 @@ 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. + This classifier is a trainer based on the Stochastic Dual Coordinate 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. @@ -21,10 +21,53 @@ 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. - + For more information, see also: + + + Scaling Up Stochastic Dual Coordinate Ascent. + + + Stochastic Dual Coordinate Ascent Methods for Regularized Loss Minimization. + + + + + + + new StochasticDualCoordinateAscentBinaryClassifier + { + MaxIterations = 100, + NumThreads = 7, + LossFunction = new SmoothedHingeLossSDCAClassificationLossFunction(), + Caching = Microsoft.ML.Models.CachingOptions.Disk + } + + + + + + + new StochasticDualCoordinateAscentClassifier + { + MaxIterations = 100, + NumThreads = 7, + LossFunction = new SmoothedHingeLossSDCAClassificationLossFunction() + } + + + + + + + new StochasticDualCoordinateAscentRegressor + { + MaxIterations = 100, + NumThreads = 5 + } + + + - \ No newline at end of file + \ No newline at end of file diff --git a/src/Microsoft.ML.Transforms/CategoricalHashTransform.cs b/src/Microsoft.ML.Transforms/CategoricalHashTransform.cs index f400d92a93..42d1f4d310 100644 --- a/src/Microsoft.ML.Transforms/CategoricalHashTransform.cs +++ b/src/Microsoft.ML.Transforms/CategoricalHashTransform.cs @@ -19,7 +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 fc1382901b..420db1b731 100644 --- a/src/Microsoft.ML.Transforms/CategoricalTransform.cs +++ b/src/Microsoft.ML.Transforms/CategoricalTransform.cs @@ -21,7 +21,7 @@ [assembly: LoadableClass(typeof(void), typeof(Categorical), null, typeof(SignatureEntryPointModule), "Categorical")] namespace Microsoft.ML.Runtime.Data { - /// + /// public static class CategoricalTransform { public enum OutputKind : byte @@ -246,7 +246,8 @@ public static class Categorical [TlcModule.EntryPoint(Name = "Transforms.CategoricalOneHotVectorizer", Desc = CategoricalTransform.Summary, UserName = CategoricalTransform.UserName, - XmlInclude = new[] { @"" })] + XmlInclude = new[] { @"", + @""})] public static CommonOutputs.TransformOutput CatTransformDict(IHostEnvironment env, CategoricalTransform.Arguments input) { Contracts.CheckValue(env, nameof(env)); @@ -261,7 +262,8 @@ public static CommonOutputs.TransformOutput CatTransformDict(IHostEnvironment en [TlcModule.EntryPoint(Name = "Transforms.CategoricalHashOneHotVectorizer", Desc = CategoricalHashTransform.Summary, UserName = CategoricalHashTransform.UserName , - XmlInclude = new[] { @"" })] + XmlInclude = new[] { @"", + @""})] public static CommonOutputs.TransformOutput CatTransformHash(IHostEnvironment env, CategoricalHashTransform.Arguments input) { Contracts.CheckValue(env, nameof(env)); @@ -273,7 +275,11 @@ public static CommonOutputs.TransformOutput CatTransformHash(IHostEnvironment en return new CommonOutputs.TransformOutput { Model = new TransformModel(env, xf, input.Data), OutputData = xf }; } - [TlcModule.EntryPoint(Name = "Transforms.TextToKeyConverter", Desc = TermTransform.Summary, UserName = TermTransform.UserName)] + [TlcModule.EntryPoint(Name = "Transforms.TextToKeyConverter", + Desc = TermTransform.Summary, + UserName = TermTransform.UserName, + XmlInclude = new[] { @"", + @"" })] public static CommonOutputs.TransformOutput TextToKey(IHostEnvironment env, TermTransform.Arguments input) { Contracts.CheckValue(env, nameof(env)); @@ -285,7 +291,10 @@ public static CommonOutputs.TransformOutput TextToKey(IHostEnvironment env, Term return new CommonOutputs.TransformOutput { Model = new TransformModel(env, xf, input.Data), OutputData = xf }; } - [TlcModule.EntryPoint(Name = "Transforms.KeyToTextConverter", Desc = "KeyToValueTransform utilizes KeyValues metadata to map key indices to the corresponding values in the KeyValues metadata.", UserName = KeyToValueTransform.UserName)] + [TlcModule.EntryPoint(Name = "Transforms.KeyToTextConverter", + Desc = "KeyToValueTransform utilizes KeyValues metadata to map key indices to the corresponding values in the KeyValues metadata.", + UserName = KeyToValueTransform.UserName, + XmlInclude = new[] { @"" })] public static CommonOutputs.TransformOutput KeyToText(IHostEnvironment env, KeyToValueTransform.Arguments input) { Contracts.CheckValue(env, nameof(env)); diff --git a/src/Microsoft.ML.Transforms/CountFeatureSelection.cs b/src/Microsoft.ML.Transforms/CountFeatureSelection.cs index 79adda882e..c01508fc30 100644 --- a/src/Microsoft.ML.Transforms/CountFeatureSelection.cs +++ b/src/Microsoft.ML.Transforms/CountFeatureSelection.cs @@ -18,11 +18,7 @@ namespace Microsoft.ML.Runtime.Data { - /// - /// Selects the slots for which the count of non-default values is greater than a threshold. - /// Uses a set of aggregators to count the number of non-default values for each slot and - /// instantiates a DropSlots transform to actually drop the slots. - /// + /// public static class CountFeatureSelectionTransform { public const string Summary = "Selects the slots for which the count of non-default values is greater than or equal to a threshold."; diff --git a/src/Microsoft.ML.Transforms/EntryPoints/SelectFeatures.cs b/src/Microsoft.ML.Transforms/EntryPoints/SelectFeatures.cs index 583b7e00ad..2d7246763f 100644 --- a/src/Microsoft.ML.Transforms/EntryPoints/SelectFeatures.cs +++ b/src/Microsoft.ML.Transforms/EntryPoints/SelectFeatures.cs @@ -11,7 +11,11 @@ namespace Microsoft.ML.Runtime.EntryPoints { public static class SelectFeatures { - [TlcModule.EntryPoint(Name = "Transforms.FeatureSelectorByCount", Desc = CountFeatureSelectionTransform.Summary, UserName = CountFeatureSelectionTransform.UserName)] + [TlcModule.EntryPoint(Name = "Transforms.FeatureSelectorByCount", + Desc = CountFeatureSelectionTransform.Summary, + UserName = CountFeatureSelectionTransform.UserName, + XmlInclude = new[] { @"", + @""})] public static CommonOutputs.TransformOutput CountSelect(IHostEnvironment env, CountFeatureSelectionTransform.Arguments input) { Contracts.CheckValue(env, nameof(env)); @@ -23,7 +27,12 @@ public static CommonOutputs.TransformOutput CountSelect(IHostEnvironment env, Co return new CommonOutputs.TransformOutput { Model = new TransformModel(env, xf, input.Data), OutputData = xf }; } - [TlcModule.EntryPoint(Name = "Transforms.FeatureSelectorByMutualInformation", Desc = MutualInformationFeatureSelectionTransform.Summary, UserName = MutualInformationFeatureSelectionTransform.UserName, ShortName = MutualInformationFeatureSelectionTransform.ShortName)] + [TlcModule.EntryPoint(Name = "Transforms.FeatureSelectorByMutualInformation", + Desc = MutualInformationFeatureSelectionTransform.Summary, + UserName = MutualInformationFeatureSelectionTransform.UserName, + ShortName = MutualInformationFeatureSelectionTransform.ShortName, + XmlInclude = new[] { @"", + @""})] public static CommonOutputs.TransformOutput MutualInformationSelect(IHostEnvironment env, MutualInformationFeatureSelectionTransform.Arguments input) { Contracts.CheckValue(env, nameof(env)); diff --git a/src/Microsoft.ML.Transforms/EntryPoints/TextAnalytics.cs b/src/Microsoft.ML.Transforms/EntryPoints/TextAnalytics.cs index d6de490d52..b37ecd5f4f 100644 --- a/src/Microsoft.ML.Transforms/EntryPoints/TextAnalytics.cs +++ b/src/Microsoft.ML.Transforms/EntryPoints/TextAnalytics.cs @@ -17,11 +17,16 @@ namespace Microsoft.ML.Runtime.Transforms /// public static class TextAnalytics { - [TlcModule.EntryPoint(Name = "Transforms.TextFeaturizer", Desc = Data.TextTransform.Summary, UserName = Data.TextTransform.UserName, ShortName = Data.TextTransform.LoaderSignature)] + [TlcModule.EntryPoint(Name = "Transforms.TextFeaturizer", + Desc = Data.TextTransform.Summary, + UserName = Data.TextTransform.UserName, + ShortName = Data.TextTransform.LoaderSignature, + XmlInclude = new[] { @"" , + @""})] public static CommonOutputs.TransformOutput TextTransform(IHostEnvironment env, TextTransform.Arguments input) { var h = EntryPointUtils.CheckArgsAndCreateHost(env, "TextTransform", input); - var xf = Microsoft.ML.Runtime.Data.TextTransform.Create(h, input, input.Data); + var xf = Data.TextTransform.Create(h, input, input.Data); return new CommonOutputs.TransformOutput() { Model = new TransformModel(h, xf, input.Data), @@ -29,8 +34,12 @@ public static CommonOutputs.TransformOutput TextTransform(IHostEnvironment env, }; } - [TlcModule.EntryPoint(Name = "Transforms.WordTokenizer", Desc = Data.DelimitedTokenizeTransform.Summary, - UserName = Data.DelimitedTokenizeTransform.UserName, ShortName = Data.DelimitedTokenizeTransform.LoaderSignature)] + [TlcModule.EntryPoint(Name = "Transforms.WordTokenizer", + Desc = Data.DelimitedTokenizeTransform.Summary, + UserName = Data.DelimitedTokenizeTransform.UserName, + ShortName = Data.DelimitedTokenizeTransform.LoaderSignature, + XmlInclude = new[] { @"", + @""})] public static CommonOutputs.TransformOutput DelimitedTokenizeTransform(IHostEnvironment env, DelimitedTokenizeTransform.Arguments input) { var h = EntryPointUtils.CheckArgsAndCreateHost(env, "DelimitedTokenizeTransform", input); @@ -42,7 +51,11 @@ public static CommonOutputs.TransformOutput DelimitedTokenizeTransform(IHostEnvi }; } - [TlcModule.EntryPoint(Name = "Transforms.NGramTranslator", Desc = Data.NgramTransform.Summary, UserName = Data.NgramTransform.UserName, ShortName = Data.NgramTransform.LoaderSignature)] + [TlcModule.EntryPoint(Name = "Transforms.NGramTranslator", + Desc = NgramTransform.Summary, + UserName = NgramTransform.UserName, + ShortName = NgramTransform.LoaderSignature, + XmlInclude = new[] { @"" })] public static CommonOutputs.TransformOutput NGramTransform(IHostEnvironment env, NgramTransform.Arguments input) { var h = EntryPointUtils.CheckArgsAndCreateHost(env, "NGramTransform", input); @@ -54,7 +67,10 @@ public static CommonOutputs.TransformOutput NGramTransform(IHostEnvironment env, }; } - [TlcModule.EntryPoint(Name = "Transforms.Dictionarizer", Desc = Data.TermTransform.Summary, UserName = Data.TermTransform.UserName, ShortName = Data.TermTransform.LoaderSignature)] + [TlcModule.EntryPoint(Name = "Transforms.Dictionarizer", + Desc = Data.TermTransform.Summary, + UserName = Data.TermTransform.UserName, + ShortName = Data.TermTransform.LoaderSignature)] public static CommonOutputs.TransformOutput TermTransform(IHostEnvironment env, TermTransform.Arguments input) { var h = EntryPointUtils.CheckArgsAndCreateHost(env, "TermTransform", input); @@ -66,7 +82,12 @@ public static CommonOutputs.TransformOutput TermTransform(IHostEnvironment env, }; } - [TlcModule.EntryPoint(Name = "Transforms.SentimentAnalyzer", Desc = "Uses a pretrained sentiment model to score input strings", UserName = SentimentAnalyzingTransform.UserName, ShortName = SentimentAnalyzingTransform.ShortName)] + [TlcModule.EntryPoint(Name = "Transforms.SentimentAnalyzer", + Desc = "Uses a pretrained sentiment model to score input strings", + UserName = SentimentAnalyzingTransform.UserName, + ShortName = SentimentAnalyzingTransform.ShortName, + XmlInclude = new[] { @"", + @""})] public static CommonOutputs.TransformOutput AnalyzeSentiment(IHostEnvironment env, SentimentAnalyzingTransform.Arguments input) { var h = EntryPointUtils.CheckArgsAndCreateHost(env, "SentimentAnalyzer", input); @@ -78,7 +99,11 @@ public static CommonOutputs.TransformOutput AnalyzeSentiment(IHostEnvironment en }; } - [TlcModule.EntryPoint(Name = "Transforms.CharacterTokenizer", Desc = CharTokenizeTransform.Summary, UserName = CharTokenizeTransform.UserName, ShortName = CharTokenizeTransform.LoaderSignature)] + [TlcModule.EntryPoint(Name = "Transforms.CharacterTokenizer", + Desc = CharTokenizeTransform.Summary, + UserName = CharTokenizeTransform.UserName, + ShortName = CharTokenizeTransform.LoaderSignature, + XmlInclude = new[] { @"" })] public static CommonOutputs.TransformOutput CharTokenize(IHostEnvironment env, CharTokenizeTransform.Arguments input) { Contracts.CheckValue(env, nameof(env)); @@ -93,7 +118,12 @@ public static CommonOutputs.TransformOutput CharTokenize(IHostEnvironment env, C }; } - [TlcModule.EntryPoint(Name = "Transforms.LightLda", Desc = LdaTransform.Summary, UserName = LdaTransform.UserName, ShortName = LdaTransform.ShortName)] + [TlcModule.EntryPoint(Name = "Transforms.LightLda", + Desc = LdaTransform.Summary, + UserName = LdaTransform.UserName, + ShortName = LdaTransform.ShortName, + XmlInclude = new[] { @"", + @"" })] public static CommonOutputs.TransformOutput LightLda(IHostEnvironment env, LdaTransform.Arguments input) { Contracts.CheckValue(env, nameof(env)); diff --git a/src/Microsoft.ML.Transforms/GcnTransform.cs b/src/Microsoft.ML.Transforms/GcnTransform.cs index a7a69ff1f4..fd67e5fca6 100644 --- a/src/Microsoft.ML.Transforms/GcnTransform.cs +++ b/src/Microsoft.ML.Transforms/GcnTransform.cs @@ -38,7 +38,7 @@ namespace Microsoft.ML.Runtime.Data /// Performs the following operation on a vector X: /// Y = (s * X - M) / D, where s is a scale, M is mean and D is either L2 norm or standard deviation. /// Usage examples and Matlab code: - /// + /// http://www.cs.stanford.edu/~acoates/papers/coatesleeng_aistats_2011.pdf. /// public sealed class LpNormNormalizerTransform : OneToOneTransformBase { @@ -666,7 +666,11 @@ private static Float Mean(Float[] src, int count, int length) public static class LpNormalization { - [TlcModule.EntryPoint(Name = "Transforms.LpNormalizer", Desc = LpNormNormalizerTransform.Summary, UserName = LpNormNormalizerTransform.UserNameLP, ShortName = LpNormNormalizerTransform.ShortNameLP)] + [TlcModule.EntryPoint(Name = "Transforms.LpNormalizer", + Desc = LpNormNormalizerTransform.Summary, + UserName = LpNormNormalizerTransform.UserNameLP, + ShortName = LpNormNormalizerTransform.ShortNameLP, + XmlInclude = new[] { @"" })] public static CommonOutputs.TransformOutput Normalize(IHostEnvironment env, LpNormNormalizerTransform.Arguments input) { var h = EntryPointUtils.CheckArgsAndCreateHost(env, "LpNormalize", input); @@ -678,7 +682,11 @@ public static CommonOutputs.TransformOutput Normalize(IHostEnvironment env, LpNo }; } - [TlcModule.EntryPoint(Name = "Transforms.GlobalContrastNormalizer", Desc = LpNormNormalizerTransform.GcnSummary, UserName = LpNormNormalizerTransform.UserNameGn, ShortName = LpNormNormalizerTransform.ShortNameGn)] + [TlcModule.EntryPoint(Name = "Transforms.GlobalContrastNormalizer", + Desc = LpNormNormalizerTransform.GcnSummary, + UserName = LpNormNormalizerTransform.UserNameGn, + ShortName = LpNormNormalizerTransform.ShortNameGn, + XmlInclude = new[] { @"" })] public static CommonOutputs.TransformOutput GcNormalize(IHostEnvironment env, LpNormNormalizerTransform.GcnArguments input) { var h = EntryPointUtils.CheckArgsAndCreateHost(env, "GcNormalize", input); diff --git a/src/Microsoft.ML.Transforms/GroupTransform.cs b/src/Microsoft.ML.Transforms/GroupTransform.cs index 2170c3b373..49c989adbf 100644 --- a/src/Microsoft.ML.Transforms/GroupTransform.cs +++ b/src/Microsoft.ML.Transforms/GroupTransform.cs @@ -664,7 +664,11 @@ public ValueGetter GetGetter(int col) public static partial class GroupingOperations { - [TlcModule.EntryPoint(Name = "Transforms.CombinerByContiguousGroupId", Desc = GroupTransform.Summary, UserName = GroupTransform.UserName, ShortName = GroupTransform.ShortName)] + [TlcModule.EntryPoint(Name = "Transforms.CombinerByContiguousGroupId", + Desc = GroupTransform.Summary, + UserName = GroupTransform.UserName, + ShortName = GroupTransform.ShortName, + XmlInclude = new[] { @"" })] public static CommonOutputs.TransformOutput Group(IHostEnvironment env, GroupTransform.Arguments input) { Contracts.CheckValue(env, nameof(env)); diff --git a/src/Microsoft.ML.Transforms/HashJoinTransform.cs b/src/Microsoft.ML.Transforms/HashJoinTransform.cs index f7c2259a3a..31f3123df5 100644 --- a/src/Microsoft.ML.Transforms/HashJoinTransform.cs +++ b/src/Microsoft.ML.Transforms/HashJoinTransform.cs @@ -193,6 +193,7 @@ public HashJoinTransform(IHostEnvironment env, { } + /// public HashJoinTransform(IHostEnvironment env, Arguments args, IDataView input) : base(env, RegistrationName, Contracts.CheckRef(args, nameof(args)).Column, input, TestColumnType) { @@ -701,7 +702,12 @@ protected override ColumnType GetColumnTypeCore(int iinfo) public static class HashJoin { - [TlcModule.EntryPoint(Name = "Transforms.HashConverter", Desc = HashJoinTransform.Summary, UserName = HashJoinTransform.UserName, ShortName = HashJoinTransform.RegistrationName)] + [TlcModule.EntryPoint(Name = "Transforms.HashConverter", + Desc = HashJoinTransform.Summary, + UserName = HashJoinTransform.UserName, + ShortName = HashJoinTransform.RegistrationName, + XmlInclude = new[] { @"", + @""})] public static CommonOutputs.TransformOutput Apply(IHostEnvironment env, HashJoinTransform.Arguments input) { Contracts.CheckValue(env, nameof(env)); diff --git a/src/Microsoft.ML.Transforms/MutualInformationFeatureSelection.cs b/src/Microsoft.ML.Transforms/MutualInformationFeatureSelection.cs index 39fec2b208..c6c5cd23e7 100644 --- a/src/Microsoft.ML.Transforms/MutualInformationFeatureSelection.cs +++ b/src/Microsoft.ML.Transforms/MutualInformationFeatureSelection.cs @@ -21,10 +21,7 @@ namespace Microsoft.ML.Runtime.Data { - /// - /// Selects the top k slots ordered by their mutual information with the label column. - /// Instantiates a DropSlots transform to actually drop the slots. - /// + /// public static class MutualInformationFeatureSelectionTransform { public const string Summary = diff --git a/src/Microsoft.ML.Transforms/NADropTransform.cs b/src/Microsoft.ML.Transforms/NADropTransform.cs index ded5add732..80e88f3ae3 100644 --- a/src/Microsoft.ML.Transforms/NADropTransform.cs +++ b/src/Microsoft.ML.Transforms/NADropTransform.cs @@ -21,9 +21,7 @@ namespace Microsoft.ML.Runtime.Data { - /// - /// Transform to drop NAs from vector columns. - /// + /// public sealed class NADropTransform : OneToOneTransformBase { public sealed class Arguments : TransformInputBase diff --git a/src/Microsoft.ML.Transforms/NAHandleTransform.cs b/src/Microsoft.ML.Transforms/NAHandleTransform.cs index 840a080ae6..746229d4f7 100644 --- a/src/Microsoft.ML.Transforms/NAHandleTransform.cs +++ b/src/Microsoft.ML.Transforms/NAHandleTransform.cs @@ -17,21 +17,7 @@ namespace Microsoft.ML.Runtime.Data { - /// - /// This transform handles missing values in the input columns. For each input column, it creates an output column - /// where the missing values are replaced by one of these specified values: - /// - The default value of the appropriate type. - /// - The mean value of the appropriate type. - /// - The max value of the appropriate type. - /// - The min value of the appropriate type. - /// (The last three work only for numeric/time span/ DateTime columns). - /// The output column can also optionally include an indicator vector for which slots were missing in the input column - /// (this can be done only when the indicator vector type can be converted to the input column type, i.e. only for numeric columns). - /// - /// When computing the mean/max/min value, there is also an option to compute it over the whole column instead of per slot. This option - /// has a default value of true for variable length vectors, and false for known length vectors. It can be changed to true for known - /// length vectors, but it results in an error if changed to false for variable length vectors. - /// + /// public static class NAHandleTransform { public enum ReplacementKind diff --git a/src/Microsoft.ML.Transforms/NAHandling.cs b/src/Microsoft.ML.Transforms/NAHandling.cs index 2ed6830782..7190291b16 100644 --- a/src/Microsoft.ML.Transforms/NAHandling.cs +++ b/src/Microsoft.ML.Transforms/NAHandling.cs @@ -11,7 +11,12 @@ namespace Microsoft.ML.Runtime.Data { public static class NAHandling { - [TlcModule.EntryPoint(Name = "Transforms.MissingValuesDropper", Desc = NADropTransform.Summary, UserName = NADropTransform.FriendlyName, ShortName = NADropTransform.ShortName)] + [TlcModule.EntryPoint(Name = "Transforms.MissingValuesDropper", + Desc = NADropTransform.Summary, + UserName = NADropTransform.FriendlyName, + ShortName = NADropTransform.ShortName, + XmlInclude = new[] { @"", + @"" })] public static CommonOutputs.TransformOutput Drop(IHostEnvironment env, NADropTransform.Arguments input) { var h = EntryPointUtils.CheckArgsAndCreateHost(env, NADropTransform.ShortName, input); @@ -23,7 +28,12 @@ public static CommonOutputs.TransformOutput Drop(IHostEnvironment env, NADropTra }; } - [TlcModule.EntryPoint(Name = "Transforms.MissingValuesRowDropper", Desc = NAFilter.Summary, UserName = NAFilter.FriendlyName, ShortName = NAFilter.ShortName)] + [TlcModule.EntryPoint(Name = "Transforms.MissingValuesRowDropper", + Desc = NAFilter.Summary, + UserName = NAFilter.FriendlyName, + ShortName = NAFilter.ShortName, + XmlInclude = new[] { @"", + @""})] public static CommonOutputs.TransformOutput Filter(IHostEnvironment env, NAFilter.Arguments input) { var h = EntryPointUtils.CheckArgsAndCreateHost(env, NAFilter.ShortName, input); @@ -35,7 +45,12 @@ public static CommonOutputs.TransformOutput Filter(IHostEnvironment env, NAFilte }; } - [TlcModule.EntryPoint(Name = "Transforms.MissingValueHandler", Desc = NAHandleTransform.Summary, UserName = NAHandleTransform.FriendlyName, ShortName = NAHandleTransform.ShortName)] + [TlcModule.EntryPoint(Name = "Transforms.MissingValueHandler", + Desc = NAHandleTransform.Summary, + UserName = NAHandleTransform.FriendlyName, + ShortName = NAHandleTransform.ShortName, + XmlInclude = new[] { @"", + @"" })] public static CommonOutputs.TransformOutput Handle(IHostEnvironment env, NAHandleTransform.Arguments input) { var h = EntryPointUtils.CheckArgsAndCreateHost(env, "NAHandle", input); @@ -47,7 +62,12 @@ public static CommonOutputs.TransformOutput Handle(IHostEnvironment env, NAHandl }; } - [TlcModule.EntryPoint(Name = "Transforms.MissingValueIndicator", Desc = NAIndicatorTransform.Summary, UserName = NAIndicatorTransform.FriendlyName, ShortName = NAIndicatorTransform.ShortName)] + [TlcModule.EntryPoint(Name = "Transforms.MissingValueIndicator", + Desc = NAIndicatorTransform.Summary, + UserName = NAIndicatorTransform.FriendlyName, + ShortName = NAIndicatorTransform.ShortName, + XmlInclude = new[] { @"", + @""})] public static CommonOutputs.TransformOutput Indicator(IHostEnvironment env, NAIndicatorTransform.Arguments input) { var h = EntryPointUtils.CheckArgsAndCreateHost(env, "NAIndicator", input); @@ -59,7 +79,12 @@ public static CommonOutputs.TransformOutput Indicator(IHostEnvironment env, NAIn }; } - [TlcModule.EntryPoint(Name = "Transforms.MissingValueSubstitutor", Desc = NAReplaceTransform.Summary, UserName = NAReplaceTransform.FriendlyName, ShortName = NAReplaceTransform.ShortName)] + [TlcModule.EntryPoint(Name = "Transforms.MissingValueSubstitutor", + Desc = NAReplaceTransform.Summary, + UserName = NAReplaceTransform.FriendlyName, + ShortName = NAReplaceTransform.ShortName, + XmlInclude = new[] { @"", + @""})] public static CommonOutputs.TransformOutput Replace(IHostEnvironment env, NAReplaceTransform.Arguments input) { var h = EntryPointUtils.CheckArgsAndCreateHost(env, "NAReplace", input); diff --git a/src/Microsoft.ML.Transforms/NAIndicatorTransform.cs b/src/Microsoft.ML.Transforms/NAIndicatorTransform.cs index c35a90d748..7607e19c61 100644 --- a/src/Microsoft.ML.Transforms/NAIndicatorTransform.cs +++ b/src/Microsoft.ML.Transforms/NAIndicatorTransform.cs @@ -21,10 +21,7 @@ namespace Microsoft.ML.Runtime.Data { - /// - /// This transform can transform either scalars or vectors (both fixed and variable size), - /// creating output columns that indicate corresponding NA values. - /// + /// public sealed class NAIndicatorTransform : OneToOneTransformBase { public sealed class Column : OneToOneColumn diff --git a/src/Microsoft.ML.Transforms/NAReplaceTransform.cs b/src/Microsoft.ML.Transforms/NAReplaceTransform.cs index 30384780e9..cfa96ea9de 100644 --- a/src/Microsoft.ML.Transforms/NAReplaceTransform.cs +++ b/src/Microsoft.ML.Transforms/NAReplaceTransform.cs @@ -27,13 +27,12 @@ namespace Microsoft.ML.Runtime.Data { - /// - /// This transform can transform either scalars or vectors (both fixed and variable size), - /// creating output columns that are identical to the input columns except for replacing NA values - /// with either the default value, user input, or imputed values (min/max/mean are currently supported). - /// Imputation modes are supported for vectors both by slot and across all slots. - /// - /// REVIEW: May make sense to implement the transform template interface. + // This transform can transform either scalars or vectors (both fixed and variable size), + // creating output columns that are identical to the input columns except for replacing NA values + // with either the default value, user input, or imputed values (min/max/mean are currently supported). + // Imputation modes are supported for vectors both by slot and across all slots. + // REVIEW: May make sense to implement the transform template interface. + /// public sealed partial class NAReplaceTransform : OneToOneTransformBase { public enum ReplacementKind diff --git a/src/Microsoft.ML.Transforms/OptionalColumnTransform.cs b/src/Microsoft.ML.Transforms/OptionalColumnTransform.cs index 9e1bad374e..b118266b7b 100644 --- a/src/Microsoft.ML.Transforms/OptionalColumnTransform.cs +++ b/src/Microsoft.ML.Transforms/OptionalColumnTransform.cs @@ -26,14 +26,8 @@ namespace Microsoft.ML.Runtime.DataPipe { - /// - /// This transform is used to mark some of the columns (e.g. Label) optional during training so that the columns are not required during scoring. - /// When applied to new data, if any of the optional columns is not present a dummy columns is created having the same properties (e.g. 'name', 'type' etc.) as used during training. - /// The columns are filled with default values. The value is - /// - scalar for scalar column - /// - totally sparse vector for vector column. - /// - public sealed class OptionalColumnTransform : RowToRowMapperTransformBase + /// + public class OptionalColumnTransform : RowToRowMapperTransformBase { public sealed class Arguments : TransformInputBase { @@ -477,7 +471,13 @@ private Delegate MakeGetterVec(int length) } } - [TlcModule.EntryPoint(Desc = Summary, Name = "Transforms.OptionalColumnCreator", UserName = UserName, ShortName = ShortName)] + [TlcModule.EntryPoint(Desc = Summary, + Name = "Transforms.OptionalColumnCreator", + UserName = UserName, + ShortName = ShortName, + XmlInclude = new[] { @"", + @""})] + public static CommonOutputs.TransformOutput MakeOptional(IHostEnvironment env, Arguments input) { var h = EntryPointUtils.CheckArgsAndCreateHost(env, "OptionalColumn", input); diff --git a/src/Microsoft.ML.Transforms/Text/LdaTransform.cs b/src/Microsoft.ML.Transforms/Text/LdaTransform.cs index 588e0a86f1..7a9b214063 100644 --- a/src/Microsoft.ML.Transforms/Text/LdaTransform.cs +++ b/src/Microsoft.ML.Transforms/Text/LdaTransform.cs @@ -26,23 +26,22 @@ namespace Microsoft.ML.Runtime.TextAnalytics { - /// - /// LightLDA transform: Big Topic Models on Modest Compute Clusters. - /// LightLDA is an implementation of Latent Dirichlet Allocation (LDA). - /// Previous implementations of LDA such as SparseLDA or AliasLDA allow to achieve massive data and model scales, - /// for example models with tens of billions of parameters to be inferred from billions of documents. - /// However this requires using a cluster of thousands of machines with all ensuing costs to setup and maintain. - /// LightLDA solves this problem in a more cost-effective manner by providing an implementation - /// that is efficient enough for modest clusters with at most tens of machines... - /// For more details please see original LightLDA paper: - /// http://arxiv.org/abs/1412.1576 - /// http://www.www2015.it/documents/proceedings/proceedings/p1351.pdf - /// and open source implementation: - /// https://github.com/Microsoft/LightLDA - /// - /// See - /// for an example on how to use LdaTransform. - /// + // LightLDA transform: Big Topic Models on Modest Compute Clusters. + // LightLDA is an implementation of Latent Dirichlet Allocation (LDA). + // Previous implementations of LDA such as SparseLDA or AliasLDA allow to achieve massive data and model scales, + // for example models with tens of billions of parameters to be inferred from billions of documents. + // However this requires using a cluster of thousands of machines with all ensuing costs to setup and maintain. + // LightLDA solves this problem in a more cost-effective manner by providing an implementation + // that is efficient enough for modest clusters with at most tens of machines... + // For more details please see original LightLDA paper: + // http://arxiv.org/abs/1412.1576 + // http://www.www2015.it/documents/proceedings/proceedings/p1351.pdf + // and open source implementation: + // https://github.com/Microsoft/LightLDA + // + // See + // for an example on how to use LdaTransform. + /// public sealed class LdaTransform : OneToOneTransformBase { public sealed class Arguments : TransformInputBase diff --git a/src/Microsoft.ML.Transforms/Text/SentimentAnalyzerTransform.cs b/src/Microsoft.ML.Transforms/Text/SentimentAnalyzerTransform.cs index 7ff3d84d10..f3471e09e0 100644 --- a/src/Microsoft.ML.Transforms/Text/SentimentAnalyzerTransform.cs +++ b/src/Microsoft.ML.Transforms/Text/SentimentAnalyzerTransform.cs @@ -17,6 +17,7 @@ namespace Microsoft.ML.Runtime.TextAnalytics { + /// public static class SentimentAnalyzingTransform { public sealed class Arguments : TransformInputBase diff --git a/src/Microsoft.ML.Transforms/Text/TextTransform.cs b/src/Microsoft.ML.Transforms/Text/TextTransform.cs index b2a34a1126..932bf63272 100644 --- a/src/Microsoft.ML.Transforms/Text/TextTransform.cs +++ b/src/Microsoft.ML.Transforms/Text/TextTransform.cs @@ -24,11 +24,10 @@ namespace Microsoft.ML.Runtime.Data using StopWordsLang = StopWordsRemoverTransform.Language; using CaseNormalizationMode = TextNormalizerTransform.CaseNormalizationMode; - /// - /// A transform that turns a collection of text documents into numerical feature vectors. The feature vectors are counts - /// of (word or character) ngrams in a given text. It offers ngram hashing (finding the ngram token string name to feature - /// integer index mapping through hashing) as an option. - /// + // A transform that turns a collection of text documents into numerical feature vectors. The feature vectors are counts + // of (word or character) ngrams in a given text. It offers ngram hashing (finding the ngram token string name to feature + // integer index mapping through hashing) as an option. + /// public static class TextTransform { /// diff --git a/src/Microsoft.ML.Transforms/Text/WordTokenizeTransform.cs b/src/Microsoft.ML.Transforms/Text/WordTokenizeTransform.cs index 60500d33cc..5afd177763 100644 --- a/src/Microsoft.ML.Transforms/Text/WordTokenizeTransform.cs +++ b/src/Microsoft.ML.Transforms/Text/WordTokenizeTransform.cs @@ -35,11 +35,10 @@ public interface ITokenizeTransform : IDataTransform { } - /// - /// The input for this transform is a DvText or a vector of DvTexts, and its output is a vector of DvTexts, - /// corresponding to the tokens in the input text, split using a set of user specified separator characters. - /// Empty strings and strings containing only spaces are dropped. - /// + // The input for this transform is a DvText or a vector of DvTexts, and its output is a vector of DvTexts, + // corresponding to the tokens in the input text, split using a set of user specified separator characters. + // Empty strings and strings containing only spaces are dropped. + /// public sealed class DelimitedTokenizeTransform : OneToOneTransformBase, ITokenizeTransform { public class Column : OneToOneColumn diff --git a/src/Microsoft.ML.Transforms/Text/doc.xml b/src/Microsoft.ML.Transforms/Text/doc.xml new file mode 100644 index 0000000000..5f734e1cfd --- /dev/null +++ b/src/Microsoft.ML.Transforms/Text/doc.xml @@ -0,0 +1,188 @@ + + + + + + + A transform that turns a collection of text documents into numerical feature vectors. + The feature vectors are normalized counts of (word and/or character) ngrams in a given tokenized text. + + + The TextFeaturizer transform gives user one-stop solution for doing: + + Language Detection + Tokenzation​ + Text normalization + Predefined and custom stopwords removal. + Word-based or character-based Ngram and SkipGram extraction.​ + TF, IDF or TF-IDF. + L-p vector normalization.​ + + The TextFeaturizer will show the transformed text, after being applied. + It converts a collection of text columns to a matrix of token ngrams/skip-grams counts. + Features are made of (word/character) n-grams/skip-grams​ and the number of features are equal to the vocabulary size found by analyzing the data. + + + + + + pipeline.Add(new TextFeaturizer("Features", "SentimentText") + { + KeepDiacritics = false, + KeepPunctuations = false, + TextCase = TextNormalizerTransformCaseNormalizationMode.Lower, + OutputTokens = true, + StopWordsRemover = new PredefinedStopWordsRemover(), + VectorNormalizer = TextTransformTextNormKind.L2, + CharFeatureExtractor = new NGramNgramExtractor() { NgramLength = 3, AllLengths = false }, + WordFeatureExtractor = new NGramNgramExtractor() { NgramLength = 2, AllLengths = true } + }); + + + + + + + This transform splits the text into words using the separator character(s). + + + The input for this transform is a DvText or a vector of DvTexts, + and its output is a vector of DvTexts, corresponding to the tokens in the input text. + The output is generated by splitting the input text, using a set of user specified separator characters. + Empty strings and strings containing only spaces are dropped. + This transform is not typically used on its own, but it is one of the transforms composing the Text Featurizer. + + + + + + pipeline.Add( new WordTokenizer("TextColumn") + { + TermSeparators = "' ', '\t', ';'" + }); + + + + + + + This transform produces a bag of counts of n-grams (sequences of consecutive values of length 1-n) in a given vector of keys. + It does so by building a dictionary of n-grams and using the id in the dictionary as the index in the bag. + + + This transform produces a matrix of token ngrams/skip-grams counts for a given corpus of text. + The n-grams are represented as count vectors, with vector slots corresponding to n-grams. + Embedding ngrams in a vector space allows their contents to be compared in an efficient manner. + The slot values in the vector can be weighted by the following factors: + + + term frequency + the number of occurrences of the slot in the text + + + inverse document frequency + a ratio (the logarithm of inverse relative slot frequency) + that measures the information a slot provides by determining how common or rare it is across the entire text. + + + term frequency-inverse document frequency + the product term frequency and the inverse document frequency. + + + This transform is not typically used on its own, but it is one of the transforms composing the Text Featurizer . + + + + + + + + pipeline.Add(new NGramTranslator("TextColumn") + { + Weighting=NgramTransformWeightingCriteria.TfIdf + }); + + + + + + + Uses a pretrained sentiment model to score input strings. + + + The Sentiment transform returns the probability that the sentiment of a natural text is positive. + + The model was trained with the Sentiment-specific word embedding (SSWE) and NGramFeaturizer on Twitter sentiment data, + similarly to the sentiment analysis part of the + Text Analytics cognitive service. + The transform outputs a score between 0 and 1 as a sentiment prediction + (where 0 is a negative sentiment and 1 is a positive sentiment). + Currently it supports only English. + + + + + + pipeline.Add(new SentimentAnalyzer() + { + Source = "TextColumn" + }); + + + + + + + This transform breaks text into individual tokens, each consisting of an individual character. + + + This transform is not typically used on its own, but it is one of the transforms composing the + Text Featurizer. + + + + + + + + pipeline.Add(new CharacterTokenizer("TextCol1" , "TextCol2" )); + + + + + + + The LDA transform implements LightLDA, a state-of-the-art implementation of Latent Dirichlet Allocation. + + + Latent Dirichlet Allocation is a well-known topic modeling algorithm that infers topical structure from text data, + and can be used to featurize any text fields as low-dimensional topical vectors. + LightLDA is an extremely efficient implementation of LDA developed in MSR-Asia that incorporates a number of + optimization techniques. See LightLDA: Big Topic Models on Modest Compute Clusters. + + + With the LDA transform, ML.NET users can train a topic model to produce 1 million topics with 1 million vocabulary + on a 1-billion-token document set one a single machine in a few hours (typically, LDA at this scale takes days and requires large clusters). + The most significant innovation is a super-efficient O(1) Metropolis-Hastings sampling algorithm, + whose running cost is (surprisingly) agnostic of model size, + allowing it to converges nearly an order of magnitude faster than other Gibbs samplers. + + + For more details please see original LightLDA paper, and its open source implementation. + + LightLDA: Big Topic Models on Modest Computer Clusters + LightLDA + + + + + + + + pipeline.Add(new LightLda(("InTextCol" , "OutTextCol"))); + + + + + + diff --git a/src/Microsoft.ML.Transforms/UngroupTransform.cs b/src/Microsoft.ML.Transforms/UngroupTransform.cs index 49cae8ae6e..ad6c31ae96 100644 --- a/src/Microsoft.ML.Transforms/UngroupTransform.cs +++ b/src/Microsoft.ML.Transforms/UngroupTransform.cs @@ -22,28 +22,28 @@ namespace Microsoft.ML.Runtime.Data { - /// - /// This can be thought of as an inverse of . For all specified vector columns - /// ("pivot" columns), performs the "ungroup" (or "unroll") operation as outlined below. - /// - /// If the only pivot column is called P, and has size K, then for every row of the input we will produce - /// K rows, that are identical in all columns except P. The column P will become a scalar column, and this - /// column will hold all the original values of input's P, one value per row, in order. The order of columns - /// will remain the same. - /// - /// Variable-length pivot columns are supported (including zero, which will eliminate the row from the result). - /// - /// Multiple pivot columns are also supported: - /// * A number of output rows is controlled by the 'mode' parameter. - /// - outer: it is equal to the maximum length of pivot columns, - /// - inner: it is equal to the minimum length of pivot columns, - /// - first: it is equal to the length of the first pivot column. - /// * If a particular pivot column has size that is different than the number of output rows, the extra slots will - /// be ignored, and the missing slots will be 'padded' with default values. - /// - /// All metadata is preserved for the retained columns. For 'unrolled' columns, all known metadata - /// except slot names is preserved. - /// + + // This can be thought of as an inverse of GroupTransform. For all specified vector columns + // ("pivot" columns), performs the "ungroup" (or "unroll") operation as outlined below. + // + // If the only pivot column is called P, and has size K, then for every row of the input we will produce + // K rows, that are identical in all columns except P. The column P will become a scalar column, and this + // column will hold all the original values of input's P, one value per row, in order. The order of columns + // will remain the same. + // + // Variable-length pivot columns are supported (including zero, which will eliminate the row from the result). + // + // Multiple pivot columns are also supported: + // * A number of output rows is controlled by the 'mode' parameter. + // - outer: it is equal to the maximum length of pivot columns, + // - inner: it is equal to the minimum length of pivot columns, + // - first: it is equal to the length of the first pivot column. + // * If a particular pivot column has size that is different than the number of output rows, the extra slots will + // be ignored, and the missing slots will be 'padded' with default values. + // + // All metadata is preserved for the retained columns. For 'unrolled' columns, all known metadata + // except slot names is preserved. + /// public sealed class UngroupTransform : TransformBase { public const string Summary = "Un-groups vector columns into sequences of rows, inverse of Group transform"; @@ -653,7 +653,12 @@ private ValueGetter MakeGetter(int col, PrimitiveType itemType) public static partial class GroupingOperations { - [TlcModule.EntryPoint(Name = "Transforms.Segregator", Desc = UngroupTransform.Summary, UserName = UngroupTransform.UserName, ShortName = UngroupTransform.ShortName)] + [TlcModule.EntryPoint(Name = "Transforms.Segregator", + Desc = UngroupTransform.Summary, + UserName = UngroupTransform.UserName, + ShortName = UngroupTransform.ShortName, + XmlInclude = new[] { @"", + @""})] public static CommonOutputs.TransformOutput Ungroup(IHostEnvironment env, UngroupTransform.Arguments input) { Contracts.CheckValue(env, nameof(env)); diff --git a/src/Microsoft.ML.Transforms/WhiteningTransform.cs b/src/Microsoft.ML.Transforms/WhiteningTransform.cs index 8b36078a04..be83e87c89 100644 --- a/src/Microsoft.ML.Transforms/WhiteningTransform.cs +++ b/src/Microsoft.ML.Transforms/WhiteningTransform.cs @@ -42,7 +42,7 @@ public enum WhiteningKind /// That is, PCA whitening is essentially just a PCA + rescale. /// ZCA whitening tries to make resulting data to look more like input data by rotating it back to the /// original input space. - /// More information: + /// More information: http://ufldl.stanford.edu/wiki/index.php/Whitening /// public sealed class WhiteningTransform : OneToOneTransformBase { diff --git a/src/Microsoft.ML.Transforms/doc.xml b/src/Microsoft.ML.Transforms/doc.xml index 7482c3a272..cb6ef6af25 100644 --- a/src/Microsoft.ML.Transforms/doc.xml +++ b/src/Microsoft.ML.Transforms/doc.xml @@ -1,5 +1,5 @@  - + @@ -11,12 +11,19 @@ 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 }); + + pipeline.Add(new CategoricalHashOneHotVectorizer("Text1") + { + HashBits = 10, + Seed = 314489979, + OutputKind = CategoricalTransformOutputKind.Bag + }); - + @@ -39,14 +46,347 @@ 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 + 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")); + + + + + Selects the slots for which the count of non-default values is greater than or equal to a threshold. + + + + This transform uses a set of aggregators to count the number of non-default values for each slot and + instantiates a to actually drop the slots. + This transform is useful when applied together with a . + The count feature selection can remove those features generated by the hash transform that have no data in the examples. + + + + + + + pipeline.Add(new FeatureSelectorByCount + { + Column = new[]{ "Feature1" }, + Count = 2 + }); + + + + + + + Selects the top k slots across all specified columns ordered by their mutual information with the label column. + + + + The mutual information of two random variables X and Y is a measure of the mutual dependence between the variables. + Formally, the mutual information can be written as: + + I(X;Y) = E[log(p(x,y)) - log(p(x)) - log(p(y))] + where the expectation is taken over the joint distribution of X and Y. + Here p(x,y) is the joint probability density function of X and Y, p(x) and p(y) are the marginal probability density functions of X and Y respectively. + In general, a higher mutual information between the dependent variable (or label) and an independent variable (or feature) means + that the label has higher mutual dependence over that feature. + It keeps the top SlotsInOutput features with the largest mutual information with the label. + + + + + + + pipeline.Add(new FeatureSelectorByMutualInformation + { + Column = new[]{ "Feature1" }, + SlotsInOutput = 6 + }); + + + + + + + Creates a new column with the specified type and default values. + + + If the user wish to create additional columns with a particular type and default values, + or replicated the values from one column to another, changing their type, they can do so using this transform. + This transform can be used as a workaround to create a Label column after deserializing a model, for prediction. + Some transforms in the serialized model operate on the Label column, and would throw errors during prediction if such a column is not found. + + + + + + pipeline.Add(new OptionalColumnCreator + { + Column = new[]{ "OptColumn"} + }); + + + + + + + Converts multiple column values into hashes. + This transform accepts both numeric and text inputs, both single and vector-valued columns. + + + This transform can be helpful for ranking and cross-validation. In the case of ranking, where the GroupIdColumn column is required, + and needs to be of a key type you can use the to hash the text value of a single GroupID column into a key value. + If the GroupID is the combination of the values from multiple columns, you can use the HashConverter to hash multiple text columns into one key column. + Similarly with CrossValidator and the StratificationColumn. + + + + + + pipeline.Add(new HashConverter("Column1", "Column2")); + + + + + + + Removes missing values from vector type columns. + + + + + + + pipeline.Add(new MissingValuesDropper("Column1")); + + + + + + + This transform can transform either scalars or vectors (both fixed and variable size), + creating output columns that indicate, through the true/false booleans whether the row has a missing value. + + + + + + + pipeline.Add(new MissingValueIndicator("Column1")); + + + + + + + Create an output column of the same type and size of the input column, + where missing values are replaced with either the default value or the mean/min/max value (for non-text columns only). + + + This transform can transform either scalars or vectors (both fixed and variable size), + creating output columns that are identical to the input columns except for replacing NA values + with either the default value, user input, or imputed values (min/max/mean are currently supported). + Imputation modes are supported for vectors both by slot and across all slots. + + + + + + + pipeline.Add(new MissingValueSubstitutor("FeatureCol") + { + ReplacementKind = NAReplaceTransformReplacementKind.Mean + }); + + + + + + + Handle missing values by replacing them with either the default value or the indicated value. + + + This transform handles missing values in the input columns. For each input column, it creates an output column + where the missing values are replaced by one of these specified values: + + + The default value of the appropriate type. + + + The mean value of the appropriate type. + + + The max value of the appropriate type. + + + The min value of the appropriate type. + + + The last three work only for numeric/TimeSpan/DateTime kind columns. + + The output column can also optionally include an indicator vector for which slots were missing in the input column. + This can be done only when the indicator vector type can be converted to the input column type, i.e. only for numeric columns. + + + When computing the mean/max/min value, there is also an option to compute it over the whole column instead of per slot. + This option has a default value of true for variable length vectors, and false for known length vectors. + It can be changed to true for known length vectors, but it results in an error if changed to false for variable length vectors. + + + + + + + + + pipeline.Add(new MissingValueHandler("FeatureCol", "CleanFeatureCol") + { + ReplaceWith = NAHandleTransformReplacementKind.Mean + }); + + + + + + + The LpNormalizer transforms, normalizes vectors (rows) individually by rescaling them to unit norm (L2, L1 or LInf). + Performs the following operation on a vector X: + Y = (X - M) / D + where M is mean and D is either L2 norm, L1 norm or LInf norm. + + + Scaling inputs to unit norms is a common operation for text classification or clustering. + For more information see: + + + + + pipeline.Add(new LpNormalizer("FeatureCol") + { + NormKind = LpNormNormalizerTransformNormalizerKind.L1Norm + }); + + + + + + + Performs a global contrast normalization on input values: + Y = (s * X - M) / D + where s is a scale, M is mean and D is either the L2 norm or standard deviation. + + + Scaling inputs to unit norms is a common operation for text classification or clustering. + For more information see: + + + + + pipeline.Add(new GlobalContrastNormalizer("FeatureCol") + { + SubMean= false + }); + + + + + + + Un-groups vector columns into sequences of rows, inverse of Group transform. + + + This can be thought of as an inverse of the . + For all specified vector columns ("pivot" columns), performs the "ungroup" (or "unroll") operation as outlined below. + + If the only pivot column is called P, and has size K, then for every row of the input we will produce + K rows, that are identical in all columns except P. The column P will become a scalar column, and this + column will hold all the original values of input's P, one value per row, in order. The order of columns + will remain the same. + + Variable-length pivot columns are supported (including zero, which will eliminate the row from the result). + Multiple pivot columns are also supported: + + A number of output rows is controlled by the 'mode' parameter. + + outer it is equal to the maximum length of pivot columns + inner it is equal to the minimum length of pivot columns + first it is equal to the length of the first pivot column + + + + + If a particular pivot column has size that is different than the number of output rows, the extra slots will + be ignored, and the missing slots will be 'padded' with default values. + + + All metadata is preserved for the retained columns. For 'unrolled' columns, all known metadata + except slot names is preserved. + + + + + + + pipeline.Add(new Segregator + { + Column = new[]{"Column1" }, + Mode = UngroupTransformUngroupMode.First + }); + + + + + + + Helps retrieving the original values from a key column. + + + The KeyToTextConverter is the complement of the transform. + Since key values are an enumeration into the set of keys, most transforms that produce key valued outputs + corresponding to input values will often, wherever possible, associate a piece of KeyValue metadata with that dataset. + Transforming values into a categorical variable would be of limited use, + if we couldn't somehow backtrack to figure out what those categories actually mean. + The KeyToTextConverter enables that functionality. + + + + + + pipeline.Add(new KeyToTextConverter(("InColumn", "OutColumn" ))); + + + + + + + Groups values of a scalar column into a vector, by a contiguous group ID. + + + The CombinerByContiguousGroupId transform groups the consecutive rows that share the specified group key (or keys). + Both group keys and the aggregated values can be of arbitrary non-vector types. + The resulting data will have all the group key columns preserved, + and the aggregated columns will become variable-length vectors of the original types. + This transform essentially performs the following SQL-like operation: + SELECT GroupKey1, GroupKey2, ... GroupKeyK, LIST(Value1), LIST(Value2), ... LIST(ValueN) + FROM Data + GROUP BY GroupKey1, GroupKey2, ... GroupKeyK. + + + + + pipeline.Add(new CombinerByContiguousGroupId + { + GroupKey = new []{"Key1", "Key2" } + }); + + - + - \ No newline at end of file + \ No newline at end of file diff --git a/src/Microsoft.ML/CSharpApi.cs b/src/Microsoft.ML/CSharpApi.cs index 83723638e1..b6ce7778e1 100644 --- a/src/Microsoft.ML/CSharpApi.cs +++ b/src/Microsoft.ML/CSharpApi.cs @@ -3080,9 +3080,7 @@ public sealed partial class OneVersusAllMacroSubGraphOutput } - /// - /// One-vs-All macro (OVA) - /// + /// public sealed partial class OneVersusAll : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithWeight, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithLabel, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInput, Microsoft.ML.ILearningPipelineItem { @@ -4135,7 +4133,8 @@ public sealed class Output namespace Trainers { - /// + /// + /// public sealed partial class AveragedPerceptronBinaryClassifier : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithLabel, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInput, Microsoft.ML.ILearningPipelineItem { @@ -4639,7 +4638,8 @@ public enum Bundle : byte } - /// + /// + /// 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 { @@ -4930,7 +4930,8 @@ public FastForestBinaryClassifierPipelineStep(Output output) namespace Trainers { - /// + /// + /// 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 { @@ -5217,7 +5218,8 @@ public enum BoostedTreeArgsOptimizationAlgorithmType } - /// + /// + /// 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 { @@ -5606,7 +5608,8 @@ public FastTreeBinaryClassifierPipelineStep(Output output) namespace Trainers { - /// + /// + /// 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 { @@ -6030,7 +6033,8 @@ public FastTreeRankerPipelineStep(Output output) namespace Trainers { - /// + /// + /// 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 { @@ -6414,7 +6418,7 @@ public FastTreeRegressorPipelineStep(Output output) namespace Trainers { - /// + /// 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 { @@ -6803,7 +6807,8 @@ public FastTreeTweedieRegressorPipelineStep(Output output) namespace Trainers { - /// + /// + /// public sealed partial class FieldAwareFactorizationMachineBinaryClassifier : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithLabel, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInput, Microsoft.ML.ILearningPipelineItem { @@ -7230,7 +7235,8 @@ public enum KMeansPlusPlusTrainerInitAlgorithm } - /// + /// + /// public sealed partial class KMeansPlusPlusClusterer : Microsoft.ML.Runtime.EntryPoints.CommonInputs.IUnsupervisedTrainerWithWeight, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInput, Microsoft.ML.ILearningPipelineItem { @@ -7346,7 +7352,8 @@ public enum LightGbmArgumentsEvalMetricType } - /// + /// + /// 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 { @@ -7549,7 +7556,8 @@ public LightGbmBinaryClassifierPipelineStep(Output output) namespace Trainers { - /// + /// + /// 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 { @@ -7752,7 +7760,8 @@ public LightGbmClassifierPipelineStep(Output output) namespace Trainers { - /// + /// + /// 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 { @@ -7955,7 +7964,8 @@ public LightGbmRankerPipelineStep(Output output) namespace Trainers { - /// + /// + /// 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 { @@ -8293,8 +8303,8 @@ public LinearSvmBinaryClassifierPipelineStep(Output output) namespace Trainers { - /// - /// + /// + /// 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 { @@ -8442,8 +8452,8 @@ public LogisticRegressionBinaryClassifierPipelineStep(Output output) namespace Trainers { - /// - /// + /// + /// 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 { @@ -8591,9 +8601,8 @@ public LogisticRegressionClassifierPipelineStep(Output output) namespace Trainers { - /// - /// Train a MultiClassNaiveBayesTrainer. - /// + /// + /// public sealed partial class NaiveBayesClassifier : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithLabel, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInput, Microsoft.ML.ILearningPipelineItem { @@ -8664,7 +8673,8 @@ public NaiveBayesClassifierPipelineStep(Output output) namespace Trainers { - /// + /// + /// public sealed partial class OnlineGradientDescentRegressor : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithLabel, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInput, Microsoft.ML.ILearningPipelineItem { @@ -8817,7 +8827,8 @@ public OnlineGradientDescentRegressorPipelineStep(Output output) namespace Trainers { - /// + /// + /// public sealed partial class PcaAnomalyDetector : Microsoft.ML.Runtime.EntryPoints.CommonInputs.IUnsupervisedTrainerWithWeight, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInput, Microsoft.ML.ILearningPipelineItem { @@ -8911,7 +8922,8 @@ public PcaAnomalyDetectorPipelineStep(Output output) namespace Trainers { - /// + /// + /// 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 { @@ -9054,7 +9066,8 @@ public PoissonRegressorPipelineStep(Output output) namespace Trainers { - /// + /// + /// public sealed partial class StochasticDualCoordinateAscentBinaryClassifier : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithLabel, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInput, Microsoft.ML.ILearningPipelineItem { @@ -9193,7 +9206,8 @@ public StochasticDualCoordinateAscentBinaryClassifierPipelineStep(Output output) namespace Trainers { - /// + /// + /// public sealed partial class StochasticDualCoordinateAscentClassifier : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithLabel, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInput, Microsoft.ML.ILearningPipelineItem { @@ -9316,7 +9330,8 @@ public StochasticDualCoordinateAscentClassifierPipelineStep(Output output) namespace Trainers { - /// + /// + /// public sealed partial class StochasticDualCoordinateAscentRegressor : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInputWithLabel, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITrainerInput, Microsoft.ML.ILearningPipelineItem { @@ -9919,7 +9934,8 @@ public sealed partial class CategoricalHashTransformColumn : OneToOneColumn + /// + /// public sealed partial class CategoricalHashOneHotVectorizer : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITransformInput, Microsoft.ML.ILearningPipelineItem { @@ -10092,7 +10108,8 @@ public sealed partial class CategoricalTransformColumn : OneToOneColumn + /// + /// public sealed partial class CategoricalOneHotVectorizer : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITransformInput, Microsoft.ML.ILearningPipelineItem { @@ -10234,9 +10251,7 @@ public sealed partial class CharTokenizeTransformColumn : OneToOneColumn - /// Character-oriented tokenizer where text is considered a sequence of characters. - /// + /// public sealed partial class CharacterTokenizer : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITransformInput, Microsoft.ML.ILearningPipelineItem { @@ -10827,9 +10842,7 @@ public ColumnTypeConverterPipelineStep(Output output) namespace Transforms { - /// - /// Groups values of a scalar column into a vector, by a contiguous group ID - /// + /// public sealed partial class CombinerByContiguousGroupId : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITransformInput, Microsoft.ML.ILearningPipelineItem { @@ -11404,9 +11417,8 @@ public FeatureCombinerPipelineStep(Output output) namespace Transforms { - /// - /// Selects the slots for which the count of non-default values is greater than or equal to a threshold. - /// + /// + /// public sealed partial class FeatureSelectorByCount : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITransformInput, Microsoft.ML.ILearningPipelineItem { @@ -11474,9 +11486,8 @@ public FeatureSelectorByCountPipelineStep(Output output) namespace Transforms { - /// - /// Selects the top k slots across all specified columns ordered by their mutual information with the label column. - /// + /// + /// public sealed partial class FeatureSelectorByMutualInformation : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITransformInput, Microsoft.ML.ILearningPipelineItem { @@ -11583,9 +11594,7 @@ public sealed partial class LpNormNormalizerTransformGcnColumn : OneToOneColumn< } - /// - /// Performs a global contrast normalization on input values: Y = (s * X - M) / D, where s is a scale, M is mean and D is either L2 norm or standard deviation. - /// + /// public sealed partial class GlobalContrastNormalizer : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITransformInput, Microsoft.ML.ILearningPipelineItem { @@ -11742,9 +11751,8 @@ public sealed partial class HashJoinTransformColumn : OneToOneColumn - /// Converts column values into hashes. This transform accepts both numeric and text inputs, both single and vector-valued columns. This is a part of the Dracula transform. - /// + /// + /// public sealed partial class HashConverter : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITransformInput, Microsoft.ML.ILearningPipelineItem { @@ -11881,9 +11889,7 @@ public sealed partial class KeyToValueTransformColumn : OneToOneColumn - /// KeyToValueTransform utilizes KeyValues metadata to map key indices to the corresponding values in the KeyValues metadata. - /// + /// public sealed partial class KeyToTextConverter : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITransformInput, Microsoft.ML.ILearningPipelineItem { @@ -12319,9 +12325,8 @@ public sealed partial class LdaTransformColumn : OneToOneColumn - /// The LDA transform implements LightLDA, a state-of-the-art implementation of Latent Dirichlet Allocation. - /// + /// + /// public sealed partial class LightLda : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITransformInput, Microsoft.ML.ILearningPipelineItem { @@ -12656,9 +12661,7 @@ public sealed partial class LpNormNormalizerTransformColumn : OneToOneColumn - /// Normalize vectors (rows) individually by rescaling them to unit norm (L2, L1 or LInf). Performs the following operation on a vector X: Y = (X - M) / D, where M is mean and D is either L2 norm, L1 norm or LInf norm. - /// + /// public sealed partial class LpNormalizer : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITransformInput, Microsoft.ML.ILearningPipelineItem { @@ -13075,9 +13078,8 @@ public sealed partial class NAHandleTransformColumn : OneToOneColumn - /// Handle missing values by replacing them with either the default value or the mean/min/max value (for non-text columns only). An indicator column can optionally be concatenated, if theinput column type is numeric. - /// + /// + /// public sealed partial class MissingValueHandler : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITransformInput, Microsoft.ML.ILearningPipelineItem { @@ -13209,9 +13211,8 @@ public sealed partial class NAIndicatorTransformColumn : OneToOneColumn - /// Create a boolean output column with the same number of slots as the input column, where the output value is true if the value in the input column is missing. - /// + /// + /// public sealed partial class MissingValueIndicator : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITransformInput, Microsoft.ML.ILearningPipelineItem { @@ -13328,9 +13329,8 @@ public sealed partial class NADropTransformColumn : OneToOneColumn - /// Removes NAs from vector columns. - /// + /// + /// public sealed partial class MissingValuesDropper : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITransformInput, Microsoft.ML.ILearningPipelineItem { @@ -13433,9 +13433,8 @@ public MissingValuesDropperPipelineStep(Output output) namespace Transforms { - /// - /// Filters out rows that contain missing values. - /// + /// + /// public sealed partial class MissingValuesRowDropper : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITransformInput, Microsoft.ML.ILearningPipelineItem { @@ -13541,9 +13540,8 @@ public sealed partial class NAReplaceTransformColumn : OneToOneColumn - /// Create an output column of the same type and size of the input column, where missing values are replaced with either the default value or the mean/min/max value (for non-text columns only). - /// + /// + /// public sealed partial class MissingValueSubstitutor : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITransformInput, Microsoft.ML.ILearningPipelineItem { @@ -13729,9 +13727,7 @@ public sealed partial class NgramTransformColumn : OneToOneColumn - /// 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. - /// + /// public sealed partial class NGramTranslator : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITransformInput, Microsoft.ML.ILearningPipelineItem { @@ -13919,9 +13915,8 @@ public NoOperationPipelineStep(Output output) namespace Transforms { - /// - /// If the source column does not exist after deserialization, create a column with the right type and default values. - /// + /// + /// public sealed partial class OptionalColumnCreator : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITransformInput, Microsoft.ML.ILearningPipelineItem { @@ -14023,7 +14018,8 @@ public sealed partial class PcaTransformColumn : OneToOneColumn + /// + /// public sealed partial class PcaCalculator : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITransformInput, Microsoft.ML.ILearningPipelineItem { @@ -14704,9 +14700,8 @@ public enum UngroupTransformUngroupMode } - /// - /// Un-groups vector columns into sequences of rows, inverse of Group transform - /// + /// + /// public sealed partial class Segregator : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITransformInput, Microsoft.ML.ILearningPipelineItem { @@ -14774,9 +14769,8 @@ public SegregatorPipelineStep(Output output) namespace Transforms { - /// - /// Uses a pretrained sentiment model to score input strings - /// + /// + /// public sealed partial class SentimentAnalyzer : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITransformInput, Microsoft.ML.ILearningPipelineItem { @@ -15033,9 +15027,8 @@ public sealed partial class TermLoaderArguments } - /// - /// A transform that turns a collection of text documents into numerical feature vectors. The feature vectors are normalized counts of (word and/or character) ngrams in a given tokenized text. - /// + /// + /// public sealed partial class TextFeaturizer : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITransformInput, Microsoft.ML.ILearningPipelineItem { @@ -15170,9 +15163,8 @@ public TextFeaturizerPipelineStep(Output output) namespace Transforms { - /// - /// Converts input values (words, numbers, etc.) to index in a dictionary. - /// + /// + /// public sealed partial class TextToKeyConverter : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITransformInput, Microsoft.ML.ILearningPipelineItem { @@ -15337,9 +15329,7 @@ public sealed class Output namespace Transforms { - /// - /// Trains a tree ensemble, or loads it from a file, then maps a numeric feature vector to three outputs: 1. A vector containing the individual tree outputs of the tree ensemble. 2. A vector indicating the leaves that the feature vector falls on in the tree ensemble. 3. A vector indicating the paths that the feature vector falls on in the tree ensemble. If a both a model file and a trainer are specified - will use the model file. If neither are specified, will train a default FastTree model. This can handle key labels by training a regression model towards their optionally permuted indices. - /// + /// public sealed partial class TreeLeafFeaturizer : Microsoft.ML.Runtime.EntryPoints.CommonInputs.IFeaturizerInput, Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITransformInput, Microsoft.ML.ILearningPipelineItem { @@ -15463,9 +15453,8 @@ public sealed partial class DelimitedTokenizeTransformColumn : OneToOneColumn - /// The input to this transform is text, and the output is a vector of text containing the words (tokens) in the original text. The separator is space, but can be specified as any other character (or multiple characters) if needed. - /// + /// + /// public sealed partial class WordTokenizer : Microsoft.ML.Runtime.EntryPoints.CommonInputs.ITransformInput, Microsoft.ML.ILearningPipelineItem { diff --git a/src/Microsoft.ML/Models/OnnxConverter.cs b/src/Microsoft.ML/Models/OnnxConverter.cs index f9c1b9dc0a..6a98d9faee 100644 --- a/src/Microsoft.ML/Models/OnnxConverter.cs +++ b/src/Microsoft.ML/Models/OnnxConverter.cs @@ -10,7 +10,7 @@ namespace Microsoft.ML.Models public sealed partial class OnnxConverter { /// - /// ONNX is an intermediate representation format + /// ONNX is an intermediate representation format /// for machine learning models. It is used to make models portable such that you can /// train a model using a toolkit and run it in another tookit's runtime, for example, /// you can create a model using ML.NET, export it to an ONNX-ML model file, diff --git a/src/Microsoft.ML/Runtime/EntryPoints/OneVersusAllMacro.cs b/src/Microsoft.ML/Runtime/EntryPoints/OneVersusAllMacro.cs index e4a54de040..494fe6b225 100644 --- a/src/Microsoft.ML/Runtime/EntryPoints/OneVersusAllMacro.cs +++ b/src/Microsoft.ML/Runtime/EntryPoints/OneVersusAllMacro.cs @@ -55,13 +55,13 @@ private static Tuple, Var> ProcessClass(IH ClassIndex = k, Column = new[] { - new ML.Transforms.LabelIndicatorTransformColumn - { - ClassIndex = k, - Name = label, - Source = label - } - }, + new ML.Transforms.LabelIndicatorTransformColumn + { + ClassIndex = k, + Name = label, + Source = label + } + }, Data = { VarName = node.GetInputVariable(nameof(input.TrainingData)).ToJson() } }; var exp = new Experiment(env); @@ -134,7 +134,9 @@ private static int GetNumberOfClasses(IHostEnvironment env, Arguments input, out } } - [TlcModule.EntryPoint(Desc = "One-vs-All macro (OVA)", Name = "Models.OneVersusAll")] + [TlcModule.EntryPoint(Desc = "One-vs-All macro (OVA)", + Name = "Models.OneVersusAll", + XmlInclude = new[] { @"" })] public static CommonOutputs.MacroOutput OVA( IHostEnvironment env, Arguments input,