Update doc

Author: wschin

docs/samples/Microsoft.ML.Samples/Dynamic/SDCACalibrated.cs

@@ -0,0 +1,68 @@
+using System;
+using System.Linq;
+using Microsoft.ML.Data;
+using Microsoft.ML.Trainers;
+
+namespace Microsoft.ML.Samples.Dynamic
+{
+    public class SDCACalibrated_BinaryClassificationExample
+    {
+        /// <summary>
+        /// Call <see cref="SdcaCalibratedBinaryTrainer"/> to train a logistic regression model.
+        /// Training examples are generated by calling <see cref="Samples.Utils.DatasetUtils.GenerateBinaryLabelFloatFeatureVectorSamples"/>.
+        /// The type of those examples is <see cref="SamplesUtils.DatasetUtils.FloatLabelFloatFeatureVectorSample"/>,
+        /// which contains one bool label and a float feature vector.
+        /// </summary>
+        public static void SDCACalibrated_BinaryClassification()
+        {
+            // Generate C# objects as training examples.
+            var rawData = SamplesUtils.DatasetUtils.GenerateBinaryLabelFloatFeatureVectorSamples(100);
+
+            // Information in first example.
+            // Label: true
+            Console.WriteLine("First example's label is {0}", rawData.First().Label);
+            // Features is a 10-element float[]:
+            //   [0]	1.0173254	float
+            //   [1]	0.9680227	float
+            //   [2]	0.7581612	float
+            //   [3]	0.406033158	float
+            //   [4]	0.7588848	float
+            //   [5]	1.10602713	float
+            //   [6]	0.6421779	float
+            //   [7]	1.17754972	float
+            //   [8]	0.473704457	float
+            //   [9]	0.4919063	float
+            Console.WriteLine("First example's feature vector is {0}", rawData.First().Features);
+
+            // 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.
+            var data = mlContext.Data.ReadFromEnumerable(rawData);
+
+            // ML.NET doesn't cache data set by default. Caching is very helpful when working with iterative
+            // algorithms which needs many data passes. Since SDCA is the case, we cache.
+            data = mlContext.Data.Cache(data);
+
+            // Step 2: Create a binary classifier.
+            // We set the "Label" column as the label of the dataset, and the "Features" column as the features column.
+            var pipeline = mlContext.BinaryClassification.Trainers.StochasticDualCoordinateAscentCalibrated(labelColumn: "Label", featureColumn: "Features", l2Const: 0.001f);
+
+            // Step 3: Train the pipeline created.
+            var model = pipeline.Fit(data);
+
+            // Step 4: Make prediction and evaluate its quality (on training set).
+            var prediction = model.Transform(data);
+
+            var rawPrediction = mlContext.CreateEnumerable<SamplesUtils.DatasetUtils.CalibratedBinaryClassifierOutput>(prediction, false);
+
+            // Step 5: Inspect the prediction of the first example.
+            var first = rawPrediction.First();
+
+            Console.WriteLine("The first example actual label is {0}." +
+                " The trained model assigns it a score {1} and a probability of being positive class {2}.",
+                first.Label /*true*/, first.Score /*around 3.2*/, first.Probability /*around around 0.95*/);
+        }
+    }
+}

src/Microsoft.ML.SamplesUtils/SamplesDatasetUtils.cs

@@ -371,6 +371,9 @@ public static IEnumerable<SampleVectorOfNumbersData> GetVectorOfNumbersData()
 
         private const int _simpleBinaryClassSampleFeatureLength = 10;
 
+        /// <summary>
+        /// Example with one binary label and 10 feature values.
+        /// </summary>
         public class BinaryLabelFloatFeatureVectorSample
         {
             public bool Label;
@@ -379,6 +382,17 @@ public class BinaryLabelFloatFeatureVectorSample
             public float[] Features;
         }
 
+        /// <summary>
+        /// Class used to capture prediction of <see cref="BinaryLabelFloatFeatureVectorSample"/> when
+        /// calling <see cref="CursoringUtils.CreateEnumerable"/> via on <see cref="MLContext"/>.
+        /// </summary>
+        public class CalibratedBinaryClassifierOutput
+        {
+            public bool Label;
+            public float Score;
+            public float Probability;
+        }
+
         public static IEnumerable<BinaryLabelFloatFeatureVectorSample> GenerateBinaryLabelFloatFeatureVectorSamples(int exampleCount)
         {
             var rnd = new Random(0);

src/Microsoft.ML.StandardLearners/StandardLearnersCatalog.cs

@@ -135,6 +135,8 @@ public static SdcaBinaryTrainer StochasticDualCoordinateAscent(
 
         /// <summary>
         /// Predict a target using a logistic regression model trained with the SDCA trainer.
+        /// The trained model can produce probablity via feeding output value of the linear
+        /// function to a <see cref="PlattCalibrator"/>.
         /// </summary>
         /// <param name="catalog">The binary classification catalog trainer object.</param>
         /// <param name="labelColumn">The labelColumn, or dependent variable.</param>
@@ -146,7 +148,7 @@ public static SdcaBinaryTrainer StochasticDualCoordinateAscent(
         /// <example>
         /// <format type="text/markdown">
         /// <![CDATA[
-        ///  [!code-csharp[SDCA](~/../docs/samples/docs/samples/Microsoft.ML.Samples/Dynamic/SDCA.cs)]
+        ///  [!code-csharp[SDCA](~/../docs/samples/docs/samples/Microsoft.ML.Samples/Dynamic/SDCACalibrated.cs)]
         /// ]]></format>
         /// </example>
         public static SdcaCalibratedBinaryTrainer StochasticDualCoordinateAscentCalibrated(
@@ -164,7 +166,10 @@ public static SdcaCalibratedBinaryTrainer StochasticDualCoordinateAscentCalibrat
         }
 
         /// <summary>
-        /// Predict a target using a linear binary classification model trained with the SDCA trainer.
+        /// Predict a target using a logistic regression model trained with the SDCA trainer.
+        /// The trained model can produce probablity via feeding output value of the linear
+        /// function to a <see cref="PlattCalibrator"/>. Comparing with <see cref="StochasticDualCoordinateAscentCalibrated(BinaryClassificationCatalog.BinaryClassificationTrainers, string, string, string, float?, float?, int?)"/>,
+        /// this function allows more advanced settings via accepting <see cref="SdcaCalibratedBinaryTrainer.Options"/>.
         /// </summary>
         /// <param name="catalog">The binary classification catalog trainer object.</param>
         /// <param name="options">Advanced arguments to the algorithm.</param>

test/Microsoft.ML.Tests/Scenarios/Api/CookbookSamples/CookbookSamplesDynamicApi.cs

@@ -445,6 +445,54 @@ private void CrossValidationOn(string dataPath)
             Console.WriteLine(microAccuracies.Average());
         }
 
+        [Fact]
+        public void SdcaLogisticRegression()
+        {
+            // Generate C# objects as training examples.
+            var rawData = SamplesUtils.DatasetUtils.GenerateBinaryLabelFloatFeatureVectorSamples(100);
+
+            // 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.
+            var data = mlContext.Data.ReadFromEnumerable(rawData);
+
+            // ML.NET doesn't cache data set by default. Caching is very helpful when working with iterative
+            // algorithms which needs many data passes. Since SDCA is the case, we cache.
+            data = mlContext.Data.Cache(data);
+
+            // Step 2: Create a binary classifier.
+            // We set the "Label" column as the label of the dataset, and the "Features" column as the features column.
+            var pipeline = mlContext.BinaryClassification.Trainers.StochasticDualCoordinateAscentCalibrated(labelColumn: "Label", featureColumn: "Features", l2Const: 0.001f);
+
+            // Step 3: Train the pipeline created.
+            var model = pipeline.Fit(data);
+
+            // Step 4: Make prediction and evaluate its quality (on training set).
+            var prediction = model.Transform(data);
+            var metrics = mlContext.BinaryClassification.Evaluate(prediction);
+
+            // Check a few metrics to make sure the trained model is ok.
+            Assert.InRange(metrics.Auc, 0.9, 1);
+            Assert.InRange(metrics.LogLoss, 0, 0.5);
+
+            var rawPrediction = mlContext.CreateEnumerable<SamplesUtils.DatasetUtils.CalibratedBinaryClassifierOutput>(prediction, false);
+
+            // Step 5: Inspect the prediction of the first example.
+            var first = rawPrediction.First();
+            // This is a positive example.
+            Assert.True(first.Label);
+            // Positive example should have non-negative score. 
+            Assert.True(first.Score > 0);
+            // Positive example should have high probability of belonging the positive class.
+            Assert.InRange(first.Probability, 0.8, 1);
+
+            Console.WriteLine("The first example actual label is {0}." +
+                " The trained model assigns it a score {1} and a probability of being positive class {2}.",
+                first.Label /*true*/, first.Score /*around 3.2*/, first.Probability /*around around 0.95*/);
+        }
+
         [Fact]
         public void ReadData()
         {