Docs & samples for SDCA-based trainers

docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/BinaryClassification/SDCALogisticRegression.cs → docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/BinaryClassification/StochasticDualCoordinateAscent.cs

@@ -5,7 +5,7 @@
 
 namespace Microsoft.ML.Samples.Dynamic.Trainers.BinaryClassification
 {
-    public static class SDCALogisticRegression
+    public static class StochasticDualCoordinateAscent
     {
         public static void Example()
         {

docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/BinaryClassification/SDCASupportVectorMachine.cs → docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/BinaryClassification/StochasticDualCoordinateAscentNonCalibrated.cs

@@ -4,7 +4,7 @@
 
 namespace Microsoft.ML.Samples.Dynamic.Trainers.BinaryClassification
 {
-    public static class SDCASupportVectorMachine
+    public static class StochasticDualCoordinateAscentNonCalibrated
     {
         public static void Example()
         {

docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/BinaryClassification/StochasticDualCoordinateAscentWithOptions.cs

@@ -0,0 +1,59 @@
+using Microsoft.ML;
+using Microsoft.ML.Trainers;
+
+namespace Microsoft.ML.Samples.Dynamic.Trainers.BinaryClassification
+{
+    public static class StochasticDualCoordinateAscentWithOptions
+    {
+        // In this examples we will use the adult income dataset. The goal is to predict
+        // if a person's income is above $50K or not, based on demographic information about that person.
+        // For more details about this dataset, please see https://archive.ics.uci.edu/ml/datasets/adult.
+        public static void Example()
+        {
+            // 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.
+            // Setting the seed to a fixed number in this example to make outputs deterministic.
+            var mlContext = new MLContext(seed: 0);
+
+            // Download and featurize the dataset.
+            var data = SamplesUtils.DatasetUtils.LoadFeaturizedAdultDataset(mlContext);
+
+            // Leave out 10% of data for testing.
+            var trainTestData = mlContext.BinaryClassification.TrainTestSplit(data, testFraction: 0.1);
+
+            // Define the trainer options.
+            var options = new SdcaBinaryTrainer.Options()
+            {
+                // Make the convergence tolerance tighter.
+                ConvergenceTolerance = 0.05f,
+                // Increase the maximum number of passes over training data.
+                MaxIterations = 30,
+                // Give the instances of the positive class slightly more weight.
+                PositiveInstanceWeight = 1.2f,
+            };
+
+            // Create data training pipeline.
+            var pipeline = mlContext.BinaryClassification.Trainers.StochasticDualCoordinateAscent(options);
+
+            // Fit this pipeline to the training data.
+            var model = pipeline.Fit(trainTestData.TrainSet);
+
+            // Evaluate how the model is doing on the test data.
+            var dataWithPredictions = model.Transform(trainTestData.TestSet);
+            var metrics = mlContext.BinaryClassification.Evaluate(dataWithPredictions);
+            SamplesUtils.ConsoleUtils.PrintMetrics(metrics);
+
+            // Expected output:
+            //   Accuracy: 0.85
+            //   AUC: 0.90
+            //   F1 Score: 0.66
+            //   Negative Precision: 0.89
+            //   Negative Recall: 0.92
+            //   Positive Precision: 0.70
+            //   Positive Recall: 0.63
+            //   LogLoss: 0.47
+            //   LogLossReduction: 39.77
+            //   Entropy: 0.78
+        }
+    }
+}

docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/MulticlassClassification/LightGbm.cs

@@ -5,7 +5,7 @@
 
 namespace Microsoft.ML.Samples.Dynamic.Trainers.MulticlassClassification
 {
-    class LightGbm
+    public static class LightGbm
     {
         // This example requires installation of additional nuget package <a href="https://www.nuget.org/packages/Microsoft.ML.LightGBM/">Microsoft.ML.LightGBM</a>.
         public static void Example()
@@ -14,10 +14,10 @@ public static void Example()
             // as a catalog of available operations and as the source of randomness.
             var mlContext = new MLContext();
 
-            // Create in-memory examples as C# native class.
+            // Create a list of data examples.
             var examples = DatasetUtils.GenerateRandomMulticlassClassificationExamples(1000);
 
-            // Convert native C# class to IDataView, a consumble format to ML.NET functions.
+            // Convert the examples list to an IDataView object, which is consumable by ML.NET API.
             var dataView = mlContext.Data.LoadFromEnumerable(examples);
 
             //////////////////// Data Preview ////////////////////

docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/MulticlassClassification/LightGbmWithOptions.cs

@@ -7,7 +7,7 @@
 
 namespace Microsoft.ML.Samples.Dynamic.Trainers.MulticlassClassification
 {
-    class LightGbmWithOptions
+    public static class LightGbmWithOptions
     {
         // This example requires installation of additional nuget package <a href="https://www.nuget.org/packages/Microsoft.ML.LightGBM/">Microsoft.ML.LightGBM</a>.
         public static void Example()
@@ -16,10 +16,10 @@ public static void Example()
             // as a catalog of available operations and as the source of randomness.
             var mlContext = new MLContext(seed: 0);
 
-            // Create in-memory examples as C# native class.
+            // Create a list of data examples.
             var examples = DatasetUtils.GenerateRandomMulticlassClassificationExamples(1000);
 
-            // Convert native C# class to IDataView, a consumble format to ML.NET functions.
+            // Convert the examples list to an IDataView object, which is consumable by ML.NET API.
             var dataView = mlContext.Data.LoadFromEnumerable(examples);
 
             //////////////////// Data Preview ////////////////////

docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/MulticlassClassification/StochasticDualCoordinateAscent.cs

@@ -0,0 +1,56 @@
+using Microsoft.ML.Data;
+using Microsoft.ML.SamplesUtils;
+
+namespace Microsoft.ML.Samples.Dynamic.Trainers.MulticlassClassification
+{
+    public static class StochasticDualCoordinateAscent
+    {
+        public static void Example()
+        {
+            // 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.
+            // Setting the seed to a fixed number in this example to make outputs deterministic.
+            var mlContext = new MLContext(seed: 0);
+
+            // Create a list of data examples.
+            var examples = DatasetUtils.GenerateRandomMulticlassClassificationExamples(1000);
+
+            // Convert the examples list to an IDataView object, which is consumable by ML.NET API.
+            var dataView = mlContext.Data.LoadFromEnumerable(examples);
+
+            //////////////////// Data Preview ////////////////////
+            // Label    Features
+            // AA       0.7262433,0.8173254,0.7680227,0.5581612,0.2060332,0.5588848,0.9060271,0.4421779,0.9775497,0.2737045
+            // BB       0.4919063,0.6673147,0.8326591,0.6695119,1.182151,0.230367,1.06237,1.195347,0.8771811,0.5145918
+            // CC       1.216908,1.248052,1.391902,0.4326252,1.099942,0.9262842,1.334019,1.08762,0.9468155,0.4811099
+            // DD       0.7871246,1.053327,0.8971719,1.588544,1.242697,1.362964,0.6303943,0.9810045,0.9431419,1.557455
+
+            // Create a pipeline. 
+            var pipeline =
+                    // Convert the string labels into key types.
+                    mlContext.Transforms.Conversion.MapValueToKey("Label")
+                    // Apply StochasticDualCoordinateAscent multiclass trainer.
+                    .Append(mlContext.MulticlassClassification.Trainers.StochasticDualCoordinateAscent());
+
+            // Split the data into training and test sets. Only training set is used in fitting
+            // the created pipeline. Metrics are computed on the test.
+            var split = mlContext.MulticlassClassification.TrainTestSplit(dataView, testFraction: 0.1);
+
+            // Train the model.
+            var model = pipeline.Fit(split.TrainSet);
+
+            // Do prediction on the test set.
+            var dataWithPredictions = model.Transform(split.TestSet);
+
+            // Evaluate the trained model using the test set.
+            var metrics = mlContext.MulticlassClassification.Evaluate(dataWithPredictions);
+            SamplesUtils.ConsoleUtils.PrintMetrics(metrics);
+
+            // Expected output:
+            //   Micro Accuracy: 0.82
+            //   Macro Accuracy: 0.81
+            //   Log Loss: 0.43
+            //   Log Loss Reduction: 67.93
+        }
+    }
+}

docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/MulticlassClassification/StochasticDualCoordinateAscentWithOptions.cs

@@ -0,0 +1,67 @@
+using Microsoft.ML.Data;
+using Microsoft.ML.SamplesUtils;
+using Microsoft.ML.Trainers;
+
+namespace Microsoft.ML.Samples.Dynamic.Trainers.MulticlassClassification
+{
+    public static class StochasticDualCoordinateAscentWithOptions
+    {
+        public static void Example()
+        {
+            // 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.
+            // Setting the seed to a fixed number in this example to make outputs deterministic.
+            var mlContext = new MLContext(seed: 0);
+
+            // Create a list of data examples.
+            var examples = DatasetUtils.GenerateRandomMulticlassClassificationExamples(1000);
+
+            // Convert the examples list to an IDataView object, which is consumable by ML.NET API.
+            var dataView = mlContext.Data.LoadFromEnumerable(examples);
+
+            //////////////////// Data Preview ////////////////////
+            // Label    Features
+            // AA       0.7262433,0.8173254,0.7680227,0.5581612,0.2060332,0.5588848,0.9060271,0.4421779,0.9775497,0.2737045
+            // BB       0.4919063,0.6673147,0.8326591,0.6695119,1.182151,0.230367,1.06237,1.195347,0.8771811,0.5145918
+            // CC       1.216908,1.248052,1.391902,0.4326252,1.099942,0.9262842,1.334019,1.08762,0.9468155,0.4811099
+            // DD       0.7871246,1.053327,0.8971719,1.588544,1.242697,1.362964,0.6303943,0.9810045,0.9431419,1.557455
+
+            var options = new SdcaMultiClassTrainer.Options
+            {
+                // Add custom loss
+                LossFunction = new HingeLoss.Options(),
+                // Make the convergence tolerance tighter.
+                ConvergenceTolerance = 0.05f,
+                // Increase the maximum number of passes over training data.
+                MaxIterations = 30,
+            };
+
+            // Create a pipeline. 
+            var pipeline =
+                    // Convert the string labels into key types.
+                    mlContext.Transforms.Conversion.MapValueToKey("Label")
+                    // Apply StochasticDualCoordinateAscent multiclass trainer.
+                    .Append(mlContext.MulticlassClassification.Trainers.StochasticDualCoordinateAscent(options));
+
+            // Split the data into training and test sets. Only training set is used in fitting
+            // the created pipeline. Metrics are computed on the test.
+            var split = mlContext.MulticlassClassification.TrainTestSplit(dataView, testFraction: 0.1);
+
+            // Train the model.
+            var model = pipeline.Fit(split.TrainSet);
+
+            // Do prediction on the test set.
+            var dataWithPredictions = model.Transform(split.TestSet);
+
+            // Evaluate the trained model using the test set.
+            var metrics = mlContext.MulticlassClassification.Evaluate(dataWithPredictions);
+            SamplesUtils.ConsoleUtils.PrintMetrics(metrics);
+
+            // Expected output:
+            //   Micro Accuracy: 0.82
+            //   Macro Accuracy: 0.81
+            //   Log Loss: 0.64
+            //   Log Loss Reduction: 52.51
+        }
+    }
+}

docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/Regression/StochasticDualCoordinateAscent.cs

@@ -0,0 +1,43 @@
+using System;
+using System.Linq;
+using Microsoft.ML.Data;
+
+namespace Microsoft.ML.Samples.Dynamic.Trainers.Regression
+{
+    public static class StochasticDualCoordinateAscent
+    {
+        public static void Example()
+        {
+            // 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.
+            // Setting the seed to a fixed number in this example to make outputs deterministic.
+            var mlContext = new MLContext(seed: 0);
+
+            // Create in-memory examples as C# native class and convert to IDataView
+            var data = SamplesUtils.DatasetUtils.GenerateFloatLabelFloatFeatureVectorSamples(1000);
+            var dataView = mlContext.Data.LoadFromEnumerable(data);
+
+            // Split the data into training and test sets. Only training set is used in fitting
+            // the created pipeline. Metrics are computed on the test.
+            var split = mlContext.MulticlassClassification.TrainTestSplit(dataView, testFraction: 0.1);
+
+            // Train the model.
+            var pipeline = mlContext.Regression.Trainers.StochasticDualCoordinateAscent();
+            var model = pipeline.Fit(split.TrainSet);
+
+            // Do prediction on the test set.
+            var dataWithPredictions = model.Transform(split.TestSet);
+
+            // Evaluate the trained model using the test set.
+            var metrics = mlContext.Regression.Evaluate(dataWithPredictions);
+            SamplesUtils.ConsoleUtils.PrintMetrics(metrics);
+
+            // Expected output:
+            //   L1: 0.27
+            //   L2: 0.11
+            //   LossFunction: 0.11
+            //   RMS: 0.33
+            //   RSquared: 0.56
+        }
+    }
+}

docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/Regression/StochasticDualCoordinateAscentWithOptions.cs

@@ -0,0 +1,53 @@
+using Microsoft.ML.Data;
+using Microsoft.ML.Trainers;
+
+namespace Microsoft.ML.Samples.Dynamic.Trainers.Regression
+{
+    public static class StochasticDualCoordinateAscentWithOptions
+    {
+        public static void Example()
+        {
+            // 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.
+            // Setting the seed to a fixed number in this example to make outputs deterministic.
+            var mlContext = new MLContext(seed: 0);
+
+            // Create in-memory examples as C# native class and convert to IDataView
+            var data = SamplesUtils.DatasetUtils.GenerateFloatLabelFloatFeatureVectorSamples(1000);
+            var dataView = mlContext.Data.LoadFromEnumerable(data);
+
+            // Split the data into training and test sets. Only training set is used in fitting
+            // the created pipeline. Metrics are computed on the test.
+            var split = mlContext.MulticlassClassification.TrainTestSplit(dataView, testFraction: 0.1);
+
+            // Create trainer options.
+            var options = new SdcaRegressionTrainer.Options
+            {
+                // Make the convergence tolerance tighter.
+                ConvergenceTolerance = 0.02f,
+                // Increase the maximum number of passes over training data.
+                MaxIterations = 30,
+                // Increase learning rate for bias
+                BiasLearningRate = 0.1f
+            };
+
+            // Train the model.
+            var pipeline = mlContext.Regression.Trainers.StochasticDualCoordinateAscent(options);
+            var model = pipeline.Fit(split.TrainSet);
+
+            // Do prediction on the test set.
+            var dataWithPredictions = model.Transform(split.TestSet);
+
+            // Evaluate the trained model using the test set.
+            var metrics = mlContext.Regression.Evaluate(dataWithPredictions);
+            SamplesUtils.ConsoleUtils.PrintMetrics(metrics);
+
+            // Expected output:
+            //   L1: 0.26
+            //   L2: 0.11
+            //   LossFunction: 0.11
+            //   RMS: 0.33
+            //   RSquared: 0.56
+        }
+    }
+}