resolving review comments and adding samples

Author: artidoro

docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/PriorTrainerSample.cs

@@ -0,0 +1,72 @@
+using System;
+using System.Linq;
+using Microsoft.ML.Data;
+using Microsoft.ML.Trainers;
+
+namespace Microsoft.ML.Samples.Dynamic
+{
+    public class PriorTrainerSample
+    {
+        public static void Example()
+        {
+            // Downloading the dataset from github.com/dotnet/machinelearning.
+            // This will create a sentiment.tsv file in the filesystem.
+            // You can open this file, if you want to see the data. 
+            string dataFile = SamplesUtils.DatasetUtils.DownloadSentimentDataset();
+
+            // A preview of the data. 
+            // Sentiment	SentimentText
+            //      0	    " :Erm, thank you. "
+            //      1	    ==You're cool==
+
+            // Create a new context for ML.NET operations. It can be used for exception tracking and logging, 
+            // as a catalog of available operations and as the source of randomness.
+            var mlContext = new MLContext();
+
+            // Step 1: Read the data as an IDataView.
+            // First, we define the reader: specify the data columns and where to find them in the text file.
+            var reader = mlContext.Data.CreateTextLoader(
+                columns: new[]
+                    {
+                        new TextLoader.Column("Sentiment", DataKind.R4, 0),
+                        new TextLoader.Column("SentimentText", DataKind.Text, 1)
+                    },
+                hasHeader: true
+            );
+            
+            // Read the data
+            var data = reader.Read(dataFile);
+
+            // Split it between training and test data
+            var (train, test) = mlContext.BinaryClassification.TrainTestSplit(data);
+
+            // ML.NET doesn't cache data set by default. Therefore, if one reads a data set from a file and accesses it many times, 
+            // it can be slow due to expensive featurization and disk operations. When the considered data can fit into memory, a 
+            // solution is to cache the data in memory. Caching is especially helpful when working with iterative algorithms which 
+            // needs many data passes. Since SDCA is the case, we cache. Inserting a cache step in a pipeline is also possible,
+            // please see the construction of pipeline below.
+            data = mlContext.Data.Cache(data);
+
+            // Step 2: Pipeline 
+            // Featurize the text column through the FeaturizeText API. 
+            // Then append a binary classifier, setting the "Label" column as the label of the dataset, and 
+            // the "Features" column produced by FeaturizeText as the features column.
+            var pipeline = mlContext.Transforms.Text.FeaturizeText("Features", "SentimentText")
+                    .AppendCacheCheckpoint(mlContext) // Add a data-cache step within a pipeline.
+                    .Append(mlContext.BinaryClassification.Trainers.Prior(labelColumn: "Sentiment"));
+
+            // Step 3: Train the pipeline
+            var trainedPipeline = pipeline.Fit(train);
+
+            // Step 4: Evaluate on the test set
+            var transformedData = trainedPipeline.Transform(test);
+            var evalMetrics = mlContext.BinaryClassification.Evaluate(transformedData, label: "Sentiment");
+
+            // Step 5: Inspect the output
+            Console.WriteLine("Accuracy: " + evalMetrics.Accuracy);
+
+            // Expected output:
+            // Accuracy: 0.647058823529412
+        }
+    }
+}

docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/RandomTrainerSample.cs

@@ -0,0 +1,72 @@
+using System;
+using System.Linq;
+using Microsoft.ML.Data;
+using Microsoft.ML.Trainers;
+
+namespace Microsoft.ML.Samples.Dynamic
+{
+    public class RandomTrainerSample
+    {
+        public static void Example()
+        {
+            // Downloading the dataset from github.com/dotnet/machinelearning.
+            // This will create a sentiment.tsv file in the filesystem.
+            // You can open this file, if you want to see the data. 
+            string dataFile = SamplesUtils.DatasetUtils.DownloadSentimentDataset();
+
+            // A preview of the data. 
+            // Sentiment	SentimentText
+            //      0	    " :Erm, thank you. "
+            //      1	    ==You're cool==
+
+            // Create a new context for ML.NET operations. It can be used for exception tracking and logging, 
+            // as a catalog of available operations and as the source of randomness.
+            var mlContext = new MLContext(seed: 1);
+
+            // Step 1: Read the data as an IDataView.
+            // First, we define the reader: specify the data columns and where to find them in the text file.
+            var reader = mlContext.Data.CreateTextLoader(
+                columns: new[]
+                    {
+                        new TextLoader.Column("Sentiment", DataKind.R4, 0),
+                        new TextLoader.Column("SentimentText", DataKind.Text, 1)
+                    },
+                hasHeader: true
+            );
+            
+            // Read the data
+            var data = reader.Read(dataFile);
+
+            // Split it between training and test data
+            var (train, test) = mlContext.BinaryClassification.TrainTestSplit(data);
+
+            // ML.NET doesn't cache data set by default. Therefore, if one reads a data set from a file and accesses it many times, 
+            // it can be slow due to expensive featurization and disk operations. When the considered data can fit into memory, a 
+            // solution is to cache the data in memory. Caching is especially helpful when working with iterative algorithms which 
+            // needs many data passes. Since SDCA is the case, we cache. Inserting a cache step in a pipeline is also possible,
+            // please see the construction of pipeline below.
+            data = mlContext.Data.Cache(data);
+
+            // Step 2: Pipeline 
+            // Featurize the text column through the FeaturizeText API. 
+            // Then append a binary classifier, setting the "Label" column as the label of the dataset, and 
+            // the "Features" column produced by FeaturizeText as the features column.
+            var pipeline = mlContext.Transforms.Text.FeaturizeText("Features", "SentimentText")
+                    .AppendCacheCheckpoint(mlContext) // Add a data-cache step within a pipeline.
+                    .Append(mlContext.BinaryClassification.Trainers.Random());
+
+            // Step 3: Train the pipeline
+            var trainedPipeline = pipeline.Fit(train);
+
+            // Step 4: Evaluate on the test set
+            var transformedData = trainedPipeline.Transform(test);
+            var evalMetrics = mlContext.BinaryClassification.Evaluate(transformedData, label: "Sentiment");
+
+            // Step 5: Inspect the output
+            Console.WriteLine("Accuracy: " + evalMetrics.Accuracy);
+
+            // Expected output (close to 0.5):
+            // Accuracy: 0.588235294117647
+        }
+    }
+}

docs/samples/Microsoft.ML.Samples/Dynamic/Transforms/CustomMappingSample.cs

@@ -0,0 +1,70 @@
+using System;
+using Microsoft.ML.Data;
+
+namespace Microsoft.ML.Samples.Dynamic
+{
+    public class CustomMappingSample
+    {
+        public static void Example()
+        {
+            // Create a new ML context, for ML.NET operations. It can be used for exception tracking and logging, 
+            // as well as the source of randomness.
+            var mlContext = new MLContext();
+
+            // Get a small dataset as an IEnumerable and convert it to an IDataView.
+            var data = SamplesUtils.DatasetUtils.GetInfertData();
+            var trainData = mlContext.Data.ReadFromEnumerable(data);
+
+            // Preview of the data.
+            //
+            // Age  Case  Education  Induced     Parity  PooledStratum  RowNum  ...
+            // 26   1       0-5yrs      1         6         3             1  ...
+            // 42   1       0-5yrs      1         1         1             2  ...
+            // 39   1       0-5yrs      2         6         4             3  ...
+            // 34   1       0-5yrs      2         4         2             4  ...
+            // 35   1       6-11yrs     1         3         32            5  ...
+
+            // We define the custom mapping between input and output rows that will be applied by the transformation.
+            Action<SamplesUtils.DatasetUtils.SampleInfertData, SampleInfertDataTransformed> mapping = 
+                (input, output) => output.IsUnderThirty = input.Age < 30;
+
+            // Custom transformations can be used to transform data directly, or as part of a pipeline. Below we transform data directly.
+            var transformer = mlContext.Transforms.CustomMappingTransformer(mapping, null);
+            var transformedData = transformer.Transform(trainData);
+
+            // Preview of the data.
+            //
+            // IsUnderThirty  Age   Case  Education  Induced     Parity  PooledStratum  RowNum  ...
+            // true            26    1       0-5yrs      1         6         3             1  ...
+            // false           42    1       0-5yrs      1         1         1             2  ...
+            // false           39    1       0-5yrs      2         6         4             3  ...
+            // false           34    1       0-5yrs      2         4         2             4  ...
+            // false           35    1       6-11yrs     1         3         32            5  ...
+
+            // Here instead we use it as part of a pipeline of estimators.
+            var pipeline = mlContext.Transforms.CustomMapping(mapping, null)
+                .Append(mlContext.Transforms.Concatenate(outputColumnName: "Features", inputColumnNames: new[] { "Parity", "Induced" }))
+                // It is useful to add a caching checkpoint before a trainer that does several passes over the data.
+                .AppendCacheCheckpoint(mlContext)
+                // We use binary FastTree to predict the label column that was generated by the custom mapping at the first step of the pipeline.
+                .Append(mlContext.BinaryClassification.Trainers.FastTree(labelColumn: "IsUnderThirty"));
+
+            // We can train the pipeline and use it to transform data.
+            transformedData = pipeline.Fit(trainData).Transform(trainData);
+        }
+
+        // Represents the transformed infertility dataset.
+        public class SampleInfertDataTransformed
+        {
+            public int RowNum { get; set; }
+            public string Education { get; set; }
+            public bool IsUnderThirty { get; set; }
+            public float Parity { get; set; }
+            public float Induced { get; set; }
+            public float Case { get; set; }
+            public float Spontaneous { get; set; }
+            public float Stratum { get; set; }
+            public float PooledStratum { get; set; }
+        }
+    }
+}

src/Microsoft.ML.Data/Scorers/PredictionTransformer.cs

@@ -54,6 +54,10 @@ public abstract class PredictionTransformerBase<TModel> : IPredictionTransformer
         private protected ISchemaBindableMapper BindableMapper;
         protected Schema TrainSchema;
 
+        /// <summary>
+        /// Whether a call to <see cref="GetRowToRowMapper(Schema)"/> should succeed, on an
+        /// appropriate schema.
+        /// </summary>
         public bool IsRowToRowMapper => true;
 
         /// <summary>

src/Microsoft.ML.StandardLearners/Standard/MultiClass/MultiClassNaiveBayesTrainer.cs

@@ -39,9 +39,15 @@ internal sealed class Options : LearnerInputBaseWithLabel
         {
         }
 
+        /// <summary> Return the type of prediction task.</summary>
         public override PredictionKind PredictionKind => PredictionKind.MultiClassClassification;
 
         private static readonly TrainerInfo _info = new TrainerInfo(normalization: false, caching: false);
+
+        /// <summary>
+        /// Auxiliary information about the trainer in terms of its capabilities
+        /// and requirements.
+        /// </summary>
         public override TrainerInfo Info => _info;
 
         /// <summary>
@@ -201,6 +207,7 @@ private static VersionInfo GetVersionInfo()
         private readonly VectorType _inputType;
         private readonly VectorType _outputType;
 
+        /// <summary> Return the type of prediction task.</summary>
         public override PredictionKind PredictionKind => PredictionKind.MultiClassClassification;
 
         ColumnType IValueMapper.InputType => _inputType;

src/Microsoft.ML.StandardLearners/Standard/MultiClass/Ova.cs

@@ -11,6 +11,7 @@
 using Microsoft.Data.DataView;
 using Microsoft.ML;
 using Microsoft.ML.CommandLine;
+using Microsoft.ML.Core.Data;
 using Microsoft.ML.Data;
 using Microsoft.ML.EntryPoints;
 using Microsoft.ML.Internal.Calibration;
@@ -54,6 +55,9 @@ public sealed class Ova : MetaMulticlassTrainer<MulticlassPredictionTransformer<
         /// </summary>
         internal sealed class Options : ArgumentsBase
         {
+            /// <summary>
+            /// Whether to use probabilities (vs. raw outputs) to identify top-score category.
+            /// </summary>
             [Argument(ArgumentType.AtMostOnce, HelpText = "Use probability or margins to determine max", ShortName = "useprob")]
             [TGUI(Label = "Use Probability", Description = "Use probabilities (vs. raw outputs) to identify top-score category")]
             public bool UseProbabilities = true;
@@ -169,6 +173,7 @@ private IDataView MapLabels(RoleMappedData data, int cls)
             throw Host.ExceptNotSupp($"Label column type is not supported by OVA: {lab.Type}");
         }
 
+        /// <summary> Trains and returns a <see cref="ITransformer"/>.</summary>
         public override MulticlassPredictionTransformer<OvaModelParameters> Fit(IDataView input)
         {
             var roles = new KeyValuePair<CR, string>[1];
@@ -227,6 +232,7 @@ private static VersionInfo GetVersionInfo()
 
         public ImmutableArray<object> SubModelParameters => _impl.Predictors.Cast<object>().ToImmutableArray();
 
+        /// <summary> Return the type of prediction task.</summary>
         public override PredictionKind PredictionKind => PredictionKind.MultiClassClassification;
 
         /// <summary>

src/Microsoft.ML.StandardLearners/Standard/MultiClass/Pkpd.cs

@@ -242,6 +242,7 @@ private static VersionInfo GetVersionInfo()
         private readonly TDistPredictor[] _predictors;
         private readonly IValueMapperDist[] _mappers;
 
+        /// <summary> Return the type of prediction task.</summary>
         public override PredictionKind PredictionKind => PredictionKind.MultiClassClassification;
         private readonly VectorType _inputType;
         private readonly ColumnType _outputType;