Adding 'aspirational examples' and some more baseline scenarios

Author: Pete Luferenko

test/Microsoft.ML.Tests/Microsoft.ML.Tests.csproj

@@ -2,6 +2,9 @@
   <PropertyGroup>
     <TargetFramework>netcoreapp2.0</TargetFramework>
   </PropertyGroup>
+  <ItemGroup>
+    <Compile Remove="Scenarios\Api\AspirationalExamples.cs" />
+  </ItemGroup>
 
   <ItemGroup>
     <ProjectReference Include="..\..\src\Microsoft.ML.Ensemble\Microsoft.ML.Ensemble.csproj" />
@@ -23,4 +26,8 @@
     <NativeAssemblyReference Include="FastTreeNative" />
     <NativeAssemblyReference Include="LdaNative" />
   </ItemGroup>
+  
+  <ItemGroup>
+    <None Include="Scenarios\Api\AspirationalExamples.cs" />
+  </ItemGroup>
 </Project>

test/Microsoft.ML.Tests/Scenarios/Api/AspirationalExamples.cs

@@ -0,0 +1,42 @@
+using System;
+using System.Collections.Generic;
+using System.Text;
+
+namespace Microsoft.ML.Tests.Scenarios.Api
+{
+    public class AspirationalExamples
+    {
+        public class IrisPrediction
+        {
+            public string PredictedLabel;
+        }
+
+        public class IrisData
+        {
+            public float[] Features;
+        }
+
+        public void FirstExperienceWithML()
+        {
+            // This is the 'getting started with ML' example, how we see it in our new API.
+            // It currently doesn't compile, let alone work, but we still can discuss and improve the syntax.
+
+            // Load the data into the system.
+            string dataPath = "iris-data.txt";
+            var data = TextReader.ReadFile(dataPath, c => (Label: c.LoadString(0), Features: c.LoadFloat(1, 4)));
+
+            // Assign numeric values to text in the "Label" column, because only
+            // numbers can be processed during model training.
+            var transformer = data.MakeTransformer(row => (Label: row.Label.Dictionarize(), row.Features));
+            var trainingData = transformer.Transform(data);
+
+            // Train a multiclass linear classifier.
+            var learner = new StochasticDualCoordinateAscentClassifier();
+            var classifier = learner.Train(trainingData);
+
+            // Obtain some predictions.
+            var predictionEngine = new PredictionEngine<float[], string>(classifier, inputColumn: "Features", outputColumn: "PredictedLabel");
+            string prediction = predictionEngine.Predict(new[] { 3.3f, 1.6f, 0.2f, 5.1f });
+        }
+    }
+}

test/Microsoft.ML.Tests/Scenarios/Api/SimpleTrainAndPredict.cs

@@ -20,7 +20,7 @@ public partial class ApiScenariosTests
         /// (e.g., the prediction does not happen over a file as it did during training).
         /// </summary>
         [Fact]
-        public void SimpleTrainAnPredict()
+        public void SimpleTrainAndPredict()
         {
             var dataPath = GetDataPath(SentimentDataPath);
             var testDataPath = GetDataPath(SentimentTestPath);

test/Microsoft.ML.Tests/Scenarios/Api/TrainWithInitialPredictor.cs

@@ -0,0 +1,43 @@
+using Microsoft.ML.Runtime;
+using Microsoft.ML.Runtime.Data;
+using Microsoft.ML.Runtime.FastTree;
+using Microsoft.ML.Runtime.Learners;
+using Xunit;
+
+namespace Microsoft.ML.Tests.Scenarios.Api
+{
+    public partial class ApiScenariosTests
+    {
+        /// <summary>
+        /// Train with initial predictor: Similar to the simple train scenario, but also accept a pre-trained initial model.
+        /// The scenario might be one of the online linear learners that can take advantage of this, e.g., averaged perceptron.
+        /// </summary>
+        [Fact]
+        public void TrainWithInitialPredictor()
+        {
+            var dataPath = GetDataPath(SentimentDataPath);
+
+            using (var env = new TlcEnvironment(seed: 1, conc: 1))
+            {
+                // Pipeline
+                var loader = new TextLoader(env, MakeSentimentTextLoaderArgs(), new MultiFileSource(dataPath));
+
+                var trans = TextTransform.Create(env, MakeSentimentTextTransformArgs(), loader);
+                var trainData = trans;
+
+                var cachedTrain = new CacheDataView(env, trainData, prefetch: null);
+                // Train the first predictor.
+                var trainer = new LinearClassificationTrainer(env, new LinearClassificationTrainer.Arguments
+                {
+                    NumThreads = 1
+                });
+                var trainRoles = new RoleMappedData(cachedTrain, label: "Label", feature: "Features");
+                var predictor = trainer.Train(new Runtime.TrainContext(trainRoles));
+
+                // Train the second predictor on the same data.
+                var secondTrainer = new AveragedPerceptronTrainer(env, new AveragedPerceptronTrainer.Arguments());
+                var finalPredictor = secondTrainer.Train(new TrainContext(trainRoles, initialPredictor: predictor));
+            }
+        }
+    }
+}

test/Microsoft.ML.Tests/Scenarios/Api/TrainWithValidationSet.cs

@@ -0,0 +1,52 @@
+using Microsoft.ML.Runtime.Data;
+using Microsoft.ML.Runtime.FastTree;
+using System;
+using System.Collections.Generic;
+using System.Text;
+using Xunit;
+using Microsoft.ML.Runtime.Api;
+using System.Linq;
+
+namespace Microsoft.ML.Tests.Scenarios.Api
+{
+    public partial class ApiScenariosTests
+    {
+        /// <summary>
+        /// Train with validation set: Similar to the simple train scenario, but also support a validation set.
+        /// The learner might be trees with early stopping.
+        /// </summary>
+        [Fact]
+        public void TrainWithValidationSet()
+        {
+            var dataPath = GetDataPath(SentimentDataPath);
+            var validationDataPath = GetDataPath(SentimentTestPath);
+
+            using (var env = new TlcEnvironment(seed: 1, conc: 1))
+            {
+                // Pipeline
+                var loader = new TextLoader(env, MakeSentimentTextLoaderArgs(), new MultiFileSource(dataPath));
+
+                var trans = TextTransform.Create(env, MakeSentimentTextTransformArgs(), loader);
+                var trainData = trans;
+
+                // Apply the same transformations on the validation set.
+                // Sadly, there is no way to easily apply the same loader to different data, so we either have
+                // to create another loader, or to save the loader to model file and then reload.
+                
+                // A new one is not always feasible, but this time it is.
+                var validLoader = new TextLoader(env, MakeSentimentTextLoaderArgs(), new MultiFileSource(validationDataPath));
+                var validData = ApplyTransformUtils.ApplyAllTransformsToData(env, trainData, validLoader);
+
+                // Cache both datasets.
+                var cachedTrain = new CacheDataView(env, trainData, prefetch: null);
+                var cachedValid = new CacheDataView(env, validData, prefetch: null);
+
+                // Train.
+                var trainer = new FastTreeBinaryClassificationTrainer(env, new FastTreeBinaryClassificationTrainer.Arguments());
+                var trainRoles = new RoleMappedData(cachedTrain, label: "Label", feature: "Features");
+                var validRoles = new RoleMappedData(cachedTrain, label: "Label", feature: "Features");
+                trainer.Train(new Runtime.TrainContext(trainRoles, validRoles));
+            }
+        }
+    }
+}