From 7856abddafcf98f861bc6452ecd3b8de8d7b591d Mon Sep 17 00:00:00 2001 From: Zeeshan Ahmed Date: Fri, 4 May 2018 14:54:12 -0700 Subject: [PATCH 1/6] Comments added to LearningPipeline class in accordance with #Bug 240636: Intellisense is not helpful with filling in pipeline components. --- src/Microsoft.ML/LearningPipeline.cs | 64 ++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) diff --git a/src/Microsoft.ML/LearningPipeline.cs b/src/Microsoft.ML/LearningPipeline.cs index 0ece3697a9..50f41c9dad 100644 --- a/src/Microsoft.ML/LearningPipeline.cs +++ b/src/Microsoft.ML/LearningPipeline.cs @@ -26,17 +26,64 @@ public ScorerPipelineStep(Var data, Var model) public Var Model { get; } } + + /// + /// The LearningPipeline is used to define the steps needed to perform desired machine learning task. + /// The steps are defined by adding a data loader followed by zero or more transforms (e.g. ) + /// and atmost one trainer/learner (e.g. ) into the LearningPipeline. + /// + /// + /// var pipeline = new LearningPipeline(); + /// pipeline.Add(new TextLoader <SentimentData> (dataPath, separator: ",")); + /// pipeline.Add(new TextFeaturizer("Features", "SentimentText")); + /// pipeline.Add(new FastTreeBinaryClassifier()); + /// + /// var model = pipeline.Train<SentimentData, SentimentPrediction>(); + /// + /// + /// [DebuggerTypeProxy(typeof(LearningPipelineDebugProxy))] public class LearningPipeline : ICollection { private List Items { get; } = new List(); + /// + /// Construct an empty LearningPipeline object + /// public LearningPipeline() { } + /// + /// Get the count of ML components in the LearningPipeline object + /// public int Count => Items.Count; public bool IsReadOnly => false; + + /// + /// Add transforms and trainer into the pipeline + /// E.g. + /// + /// Transforms: + /// , + /// + /// , + /// , + /// , + /// , + /// etc. + /// + /// + /// Trainers: + /// , + /// , + /// , + /// , + /// etc. + /// + /// For list of available transforms and trainers please see "Microsoft.ML.Transforms" and "Microsoft.ML.Trainers" namespaces. + /// + /// public void Add(ILearningPipelineItem item) => Items.Add(item); public void Clear() => Items.Clear(); public bool Contains(ILearningPipelineItem item) => Items.Contains(item); @@ -45,6 +92,23 @@ public LearningPipeline() public bool Remove(ILearningPipelineItem item) => Items.Remove(item); IEnumerator IEnumerable.GetEnumerator() => GetEnumerator(); + /// + /// Train the model using the ML components in the pipeline. + /// + /// Type of data instances the model will be trained on. In most cases, its a custom type defined by the user according to the structure of data. + /// E.g. + /// + /// Please see for input type definition for sentiment classification task. + /// The type is defined for a .csv file that contains sentiment classification data with Sentiment and SentimentText as two columns. + /// + /// + /// Ouput type. The prediction will be return based on this type. + /// E.g. + /// + /// For sentiment classifcation scenario, the prediction type is defined at . + /// + /// + /// PredictionModel object public PredictionModel Train() where TInput : class where TOutput : class, new() From 77d21ff1438fefa1fb11d64a543f709ccddec68b Mon Sep 17 00:00:00 2001 From: Zeeshan Ahmed Date: Fri, 4 May 2018 15:14:48 -0700 Subject: [PATCH 2/6] Comments added to LearningPipeline class in accordance with #Bug 240636: Intellisense is not helpful with filling in pipeline components. --- src/Microsoft.ML/LearningPipeline.cs | 62 ++++++++++++++++++++-------- 1 file changed, 44 insertions(+), 18 deletions(-) diff --git a/src/Microsoft.ML/LearningPipeline.cs b/src/Microsoft.ML/LearningPipeline.cs index 50f41c9dad..97f2952771 100644 --- a/src/Microsoft.ML/LearningPipeline.cs +++ b/src/Microsoft.ML/LearningPipeline.cs @@ -28,10 +28,14 @@ public ScorerPipelineStep(Var data, Var model) /// - /// The LearningPipeline is used to define the steps needed to perform desired machine learning task. - /// The steps are defined by adding a data loader followed by zero or more transforms (e.g. ) - /// and atmost one trainer/learner (e.g. ) into the LearningPipeline. + /// LearningPipeline class is used to define the steps needed to perform desired machine learning task. + /// The steps are defined by adding a data loader (e.g. ) followed by zero or more transforms (e.g. ) + /// and atmost one trainer/learner (e.g. ) in the pipeline. + /// + /// Data can be analyzed at every step by inspecting the LearningPipeline object in VS.Net debugger. /// + /// + /// For example, /// /// var pipeline = new LearningPipeline(); /// pipeline.Add(new TextLoader <SentimentData> (dataPath, separator: ",")); @@ -48,7 +52,7 @@ public class LearningPipeline : ICollection private List Items { get; } = new List(); /// - /// Construct an empty LearningPipeline object + /// Construct an empty LearningPipeline object. /// public LearningPipeline() { @@ -61,8 +65,13 @@ public LearningPipeline() public bool IsReadOnly => false; /// - /// Add transforms and trainer into the pipeline - /// E.g. + /// Add a data loader, transform or trainer into the pipeline. + /// Possible data loader(s), transforms and trainers options are + /// + /// Data Loader: + /// + /// etc. + /// /// /// Transforms: /// , @@ -81,34 +90,51 @@ public LearningPipeline() /// , /// etc. /// - /// For list of available transforms and trainers please see "Microsoft.ML.Transforms" and "Microsoft.ML.Trainers" namespaces. + /// For a complete list of transforms and trainers, please see "Microsoft.ML.Transforms" and "Microsoft.ML.Trainers" namespaces. /// /// public void Add(ILearningPipelineItem item) => Items.Add(item); + + /// + /// Remove all the transforms/trainers from the pipeline. + /// public void Clear() => Items.Clear(); + + /// + /// Check if a specific loader/transform/trainer is in the pipeline? + /// + /// Any ML component (data loader, transform or trainer) defined as ILearningPipelineItem. + /// true/false public bool Contains(ILearningPipelineItem item) => Items.Contains(item); + + /// + /// Copy the pipeline items into an array. + /// + /// Array the items are copied to. + /// Index to start copying from. public void CopyTo(ILearningPipelineItem[] array, int arrayIndex) => Items.CopyTo(array, arrayIndex); public IEnumerator GetEnumerator() => Items.GetEnumerator(); + + /// + /// Remove an item from the pipeline. + /// + /// ILearningPipelineItem to remove. + /// true/false public bool Remove(ILearningPipelineItem item) => Items.Remove(item); IEnumerator IEnumerable.GetEnumerator() => GetEnumerator(); /// /// Train the model using the ML components in the pipeline. /// - /// Type of data instances the model will be trained on. In most cases, its a custom type defined by the user according to the structure of data. - /// E.g. - /// - /// Please see for input type definition for sentiment classification task. - /// The type is defined for a .csv file that contains sentiment classification data with Sentiment and SentimentText as two columns. - /// + /// Type of data instances the model will be trained on. It's a custom type defined by the user according to the structure of data. + /// + /// E.g. please see "Microsoft.ML.Scenarios.SentimentData" in "Microsoft.ML.Tests.csproj" for input type definition for sentiment classification task. + /// The type is defined for a .csv file that contains sentiment classification data with Sentiment and SentimentText as two columns in the .csv file. /// /// Ouput type. The prediction will be return based on this type. - /// E.g. - /// - /// For sentiment classifcation scenario, the prediction type is defined at . - /// + /// E.g. for sentiment classifcation scenario, the prediction type is defined at "Microsoft.ML.Scenarios.SentimentPrediction" in "Microsoft.ML.Tests.csproj". /// - /// PredictionModel object + /// PredictionModel object. This is the model object used for prediction on new instances. public PredictionModel Train() where TInput : class where TOutput : class, new() From 5471ed12d9065fa48a901ca22dc1d2e3eb8662b3 Mon Sep 17 00:00:00 2001 From: Zeeshan Ahmed Date: Fri, 4 May 2018 16:56:33 -0700 Subject: [PATCH 3/6] Fixed a typo in namespace --- src/Microsoft.ML/LearningPipeline.cs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/Microsoft.ML/LearningPipeline.cs b/src/Microsoft.ML/LearningPipeline.cs index 97f2952771..f51d6dae4e 100644 --- a/src/Microsoft.ML/LearningPipeline.cs +++ b/src/Microsoft.ML/LearningPipeline.cs @@ -128,11 +128,11 @@ public LearningPipeline() /// /// Type of data instances the model will be trained on. It's a custom type defined by the user according to the structure of data. /// - /// E.g. please see "Microsoft.ML.Scenarios.SentimentData" in "Microsoft.ML.Tests.csproj" for input type definition for sentiment classification task. + /// E.g. please see "Microsoft.ML.Scenarios.ScenarioTests.SentimentData" in "Microsoft.ML.Tests.csproj" for input type definition for sentiment classification task. /// The type is defined for a .csv file that contains sentiment classification data with Sentiment and SentimentText as two columns in the .csv file. /// /// Ouput type. The prediction will be return based on this type. - /// E.g. for sentiment classifcation scenario, the prediction type is defined at "Microsoft.ML.Scenarios.SentimentPrediction" in "Microsoft.ML.Tests.csproj". + /// E.g. for sentiment classifcation scenario, the prediction type is defined at "Microsoft.ML.Scenarios.ScenarioTests.SentimentPrediction" in "Microsoft.ML.Tests.csproj". /// /// PredictionModel object. This is the model object used for prediction on new instances. public PredictionModel Train() From 98fc8d0180affd60983dc1501f0cc953c9c8a5f4 Mon Sep 17 00:00:00 2001 From: Zeeshan Ahmed Date: Mon, 7 May 2018 17:13:11 -0700 Subject: [PATCH 4/6] Addressed reviewers' comments. --- src/Microsoft.ML/LearningPipeline.cs | 28 ++++++++++++---------------- 1 file changed, 12 insertions(+), 16 deletions(-) diff --git a/src/Microsoft.ML/LearningPipeline.cs b/src/Microsoft.ML/LearningPipeline.cs index f51d6dae4e..0be12d1463 100644 --- a/src/Microsoft.ML/LearningPipeline.cs +++ b/src/Microsoft.ML/LearningPipeline.cs @@ -28,11 +28,11 @@ public ScorerPipelineStep(Var data, Var model) /// - /// LearningPipeline class is used to define the steps needed to perform desired machine learning task. + /// class is used to define the steps needed to perform a desired machine learning task. /// The steps are defined by adding a data loader (e.g. ) followed by zero or more transforms (e.g. ) - /// and atmost one trainer/learner (e.g. ) in the pipeline. + /// and at most one trainer/learner (e.g. ) in the pipeline. /// - /// Data can be analyzed at every step by inspecting the LearningPipeline object in VS.Net debugger. + /// /// /// /// For example, @@ -45,21 +45,20 @@ public ScorerPipelineStep(Var data, Var model) /// var model = pipeline.Train<SentimentData, SentimentPrediction>(); /// /// - /// [DebuggerTypeProxy(typeof(LearningPipelineDebugProxy))] public class LearningPipeline : ICollection { private List Items { get; } = new List(); /// - /// Construct an empty LearningPipeline object. + /// Construct an empty object. /// public LearningPipeline() { } /// - /// Get the count of ML components in the LearningPipeline object + /// Get the count of ML components in the object /// public int Count => Items.Count; public bool IsReadOnly => false; @@ -92,34 +91,32 @@ public LearningPipeline() /// /// For a complete list of transforms and trainers, please see "Microsoft.ML.Transforms" and "Microsoft.ML.Trainers" namespaces. /// - /// + /// Any ML component (data loader, transform or trainer) defined as . public void Add(ILearningPipelineItem item) => Items.Add(item); /// - /// Remove all the transforms/trainers from the pipeline. + /// Remove all the loaders/transforms/trainers from the pipeline. /// public void Clear() => Items.Clear(); /// /// Check if a specific loader/transform/trainer is in the pipeline? /// - /// Any ML component (data loader, transform or trainer) defined as ILearningPipelineItem. - /// true/false + /// Any ML component (data loader, transform or trainer) defined as . public bool Contains(ILearningPipelineItem item) => Items.Contains(item); /// /// Copy the pipeline items into an array. /// /// Array the items are copied to. - /// Index to start copying from. + /// Index in the specified to start copying into. public void CopyTo(ILearningPipelineItem[] array, int arrayIndex) => Items.CopyTo(array, arrayIndex); public IEnumerator GetEnumerator() => Items.GetEnumerator(); /// /// Remove an item from the pipeline. /// - /// ILearningPipelineItem to remove. - /// true/false + /// to remove. public bool Remove(ILearningPipelineItem item) => Items.Remove(item); IEnumerator IEnumerable.GetEnumerator() => GetEnumerator(); @@ -128,11 +125,10 @@ public LearningPipeline() /// /// Type of data instances the model will be trained on. It's a custom type defined by the user according to the structure of data. /// - /// E.g. please see "Microsoft.ML.Scenarios.ScenarioTests.SentimentData" in "Microsoft.ML.Tests.csproj" for input type definition for sentiment classification task. - /// The type is defined for a .csv file that contains sentiment classification data with Sentiment and SentimentText as two columns in the .csv file. + /// Please see https://www.microsoft.com/net/learn/apps/machine-learning-and-ai/ml-dotnet/get-started/windows for more details on input type. /// /// Ouput type. The prediction will be return based on this type. - /// E.g. for sentiment classifcation scenario, the prediction type is defined at "Microsoft.ML.Scenarios.ScenarioTests.SentimentPrediction" in "Microsoft.ML.Tests.csproj". + /// Please see https://www.microsoft.com/net/learn/apps/machine-learning-and-ai/ml-dotnet/get-started/windows for more details on output type. /// /// PredictionModel object. This is the model object used for prediction on new instances. public PredictionModel Train() From e7dc70764b7a9a67077ad2adc4df08e3d8c3843c Mon Sep 17 00:00:00 2001 From: Zeeshan Ahmed Date: Tue, 8 May 2018 10:34:33 -0700 Subject: [PATCH 5/6] Addressed reviewers' comments. --- src/Microsoft.ML/LearningPipeline.cs | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/Microsoft.ML/LearningPipeline.cs b/src/Microsoft.ML/LearningPipeline.cs index 0be12d1463..80871c1bdd 100644 --- a/src/Microsoft.ML/LearningPipeline.cs +++ b/src/Microsoft.ML/LearningPipeline.cs @@ -103,13 +103,14 @@ public LearningPipeline() /// Check if a specific loader/transform/trainer is in the pipeline? /// /// Any ML component (data loader, transform or trainer) defined as . + /// true if item is found in the pipeline; otherwise, false. public bool Contains(ILearningPipelineItem item) => Items.Contains(item); /// /// Copy the pipeline items into an array. /// - /// Array the items are copied to. - /// Index in the specified to start copying into. + /// The one-dimensional Array that is the destination of the elements copied from. + /// The zero-based index in at which copying begins. public void CopyTo(ILearningPipelineItem[] array, int arrayIndex) => Items.CopyTo(array, arrayIndex); public IEnumerator GetEnumerator() => Items.GetEnumerator(); @@ -117,6 +118,7 @@ public LearningPipeline() /// Remove an item from the pipeline. /// /// to remove. + /// true if item was removed from the pipeline; otherwise, false. public bool Remove(ILearningPipelineItem item) => Items.Remove(item); IEnumerator IEnumerable.GetEnumerator() => GetEnumerator(); From 5089e982af46b13daaeb300838f5ed4ac5f09823 Mon Sep 17 00:00:00 2001 From: Zeeshan Ahmed Date: Tue, 8 May 2018 19:23:16 -0700 Subject: [PATCH 6/6] Addressed reviewers' comments. --- src/Microsoft.ML/LearningPipeline.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Microsoft.ML/LearningPipeline.cs b/src/Microsoft.ML/LearningPipeline.cs index 80871c1bdd..8056d03418 100644 --- a/src/Microsoft.ML/LearningPipeline.cs +++ b/src/Microsoft.ML/LearningPipeline.cs @@ -28,7 +28,7 @@ public ScorerPipelineStep(Var data, Var model) /// - /// class is used to define the steps needed to perform a desired machine learning task. + /// The class is used to define the steps needed to perform a desired machine learning task. /// The steps are defined by adding a data loader (e.g. ) followed by zero or more transforms (e.g. ) /// and at most one trainer/learner (e.g. ) in the pipeline. ///