Merge branch 'feature/api-examples' into feature/estimators

Author: Pete Luferenko

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

@@ -0,0 +1,38 @@
+using Microsoft.ML.Runtime.Api;
+using Microsoft.ML.Runtime.Data;
+using Microsoft.ML.TestFramework;
+using System;
+using System.Collections.Generic;
+using System.Text;
+using Xunit.Abstractions;
+
+namespace Microsoft.ML.Tests.Scenarios.Api
+{
+    /// <summary>
+    /// Common utility functions for API scenarios tests.
+    /// </summary>
+    public partial class ApiScenariosTests : BaseTestClass
+    {
+        public ApiScenariosTests(ITestOutputHelper output) : base(output)
+        {
+        }
+
+        public const string SentimentDataPath = "wikipedia-detox-250-line-data.tsv";
+        public const string SentimentTestPath = "wikipedia-detox-250-line-test.tsv";
+
+        public class SentimentData
+        {
+            [ColumnName("Label")]
+            public bool Sentiment;
+            public string SentimentText;
+        }
+
+        public class SentimentPrediction
+        {
+            [ColumnName("PredictedLabel")]
+            public bool Sentiment;
+
+            public float Score;
+        }
+    }
+}

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

@@ -0,0 +1,109 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using Microsoft.ML.Runtime.Data;
+using Microsoft.ML.Runtime.Learners;
+using Microsoft.ML.Runtime.Api;
+using Xunit;
+using System;
+using System.Linq;
+
+namespace Microsoft.ML.Tests.Scenarios.Api
+{
+    public partial class ApiScenariosTests
+    {
+        /// <summary>
+        /// Start with a dataset in a text file. Run text featurization on text values. 
+        /// Train a linear model over that. (I am thinking sentiment classification.) 
+        /// Out of the result, produce some structure over which you can get predictions programmatically 
+        /// (e.g., the prediction does not happen over a file as it did during training).
+        /// </summary>
+        [Fact]
+        public void SimpleTrainAnPredict()
+        {
+            var dataPath = GetDataPath(SentimentDataPath);
+            var testDataPath = 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);
+
+                // Train
+                var trainer = new LinearClassificationTrainer(env, new LinearClassificationTrainer.Arguments
+                {
+                    NumThreads = 1
+                });
+
+                var cached = new CacheDataView(env, trans, prefetch: null);
+                var trainRoles = new RoleMappedData(cached, label: "Label", feature: "Features");
+                var predictor = trainer.Train(new Runtime.TrainContext(trainRoles));
+
+                var scoreRoles = new RoleMappedData(trans, label: "Label", feature: "Features");
+                IDataScorerTransform scorer = ScoreUtils.GetScorer(predictor, scoreRoles, env, trainRoles.Schema);
+
+                // Create prediction engine and test predictions.
+                var model = env.CreatePredictionEngine<SentimentData, SentimentPrediction>(scorer);
+
+                // Take a couple examples out of the test data and run predictions on top.
+                var testLoader = new TextLoader(env, MakeSentimentTextLoaderArgs(), new MultiFileSource(GetDataPath(SentimentTestPath)));
+                var testData = testLoader.AsEnumerable<SentimentData>(env, false);
+                foreach (var input in testData.Take(5))
+                {
+                    var prediction = model.Predict(input);
+                    // Verify that predictions match and scores are separated from zero.
+                    Assert.Equal(input.Sentiment, prediction.Sentiment);
+                    Assert.True(input.Sentiment && prediction.Score > 1 || !input.Sentiment && prediction.Score < -1);
+                }
+            }
+        }
+
+        private static TextTransform.Arguments MakeSentimentTextTransformArgs()
+        {
+            return new TextTransform.Arguments()
+            {
+                Column = new TextTransform.Column
+                {
+                    Name = "Features",
+                    Source = new[] { "SentimentText" }
+                },
+                KeepDiacritics = false,
+                KeepPunctuations = false,
+                TextCase = Runtime.TextAnalytics.TextNormalizerTransform.CaseNormalizationMode.Lower,
+                OutputTokens = true,
+                StopWordsRemover = new Runtime.TextAnalytics.PredefinedStopWordsRemoverFactory(),
+                VectorNormalizer = TextTransform.TextNormKind.L2,
+                CharFeatureExtractor = new NgramExtractorTransform.NgramExtractorArguments() { NgramLength = 3, AllLengths = false },
+                WordFeatureExtractor = new NgramExtractorTransform.NgramExtractorArguments() { NgramLength = 2, AllLengths = true },
+            };
+        }
+
+        private static TextLoader.Arguments MakeSentimentTextLoaderArgs()
+        {
+            return new TextLoader.Arguments()
+            {
+                Separator = "tab",
+                HasHeader = true,
+                Column = new[]
+                    {
+                        new TextLoader.Column()
+                        {
+                            Name = "Label",
+                            Source = new [] { new TextLoader.Range() { Min=0, Max=0} },
+                            Type = DataKind.BL
+                        },
+
+                        new TextLoader.Column()
+                        {
+                            Name = "SentimentText",
+                            Source = new [] { new TextLoader.Range() { Min=1, Max=1} },
+                            Type = DataKind.Text
+                        }
+                    }
+            };
+        }
+    }
+}

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

@@ -0,0 +1,68 @@
+using Microsoft.ML.Runtime.Api;
+using Microsoft.ML.Runtime.Data;
+using Microsoft.ML.Runtime.Learners;
+using Microsoft.ML.Runtime.Model;
+using System.Linq;
+using Xunit;
+
+namespace Microsoft.ML.Tests.Scenarios.Api
+{
+    public partial class ApiScenariosTests
+    {
+        /// <summary>
+        /// Train, save/load model, predict: 
+        /// Serve the scenario where training and prediction happen in different processes (or even different machines). 
+        /// The actual test will not run in different processes, but will simulate the idea that the 
+        /// "communication pipe" is just a serialized model of some form.
+        /// </summary>
+        [Fact]
+        public void TrainSaveModelAndPredict()
+        {
+            var dataPath = GetDataPath(SentimentDataPath);
+            var testDataPath = 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);
+
+                // Train
+                var trainer = new LinearClassificationTrainer(env, new LinearClassificationTrainer.Arguments
+                {
+                    NumThreads = 1
+                });
+
+                var cached = new CacheDataView(env, trans, prefetch: null);
+                var trainRoles = new RoleMappedData(cached, label: "Label", feature: "Features");
+                var predictor = trainer.Train(new Runtime.TrainContext(trainRoles));
+
+                PredictionEngine<SentimentData, SentimentPrediction> model;
+                using (var file = env.CreateTempFile())
+                {
+                    // Save model. 
+                    var scoreRoles = new RoleMappedData(trans, label: "Label", feature: "Features");
+                    using (var ch = env.Start("saving"))
+                        TrainUtils.SaveModel(env, ch, file, predictor, scoreRoles);
+
+                    // Load model.
+                    using (var fs = file.OpenReadStream())
+                        model = env.CreatePredictionEngine<SentimentData, SentimentPrediction>(fs);
+                }
+
+                // Take a couple examples out of the test data and run predictions on top.
+                var testLoader = new TextLoader(env, MakeSentimentTextLoaderArgs(), new MultiFileSource(GetDataPath(SentimentTestPath)));
+                var testData = testLoader.AsEnumerable<SentimentData>(env, false);
+                foreach (var input in testData.Take(5))
+                {
+                    var prediction = model.Predict(input);
+                    // Verify that predictions match and scores are separated from zero.
+                    Assert.Equal(input.Sentiment, prediction.Sentiment);
+                    Assert.True(input.Sentiment && prediction.Score > 1 || !input.Sentiment && prediction.Score < -1);
+                }
+            }
+
+        }
+    }
+}