Create forecasting prediction engine and conform time series forecasting API to estimator standards. (#3910)

* forecast API.

* refactor code.

* refactor code.

* fix.

* fix.

* fix.

* fix.

* fix.

* Update documentation.

* fix.

* Update documentation.

* Update tests.

* clean up tests.

* Update with PR review comment and entrypoint for forecasting API.

* Make GrowthRatio accessible in nimbus ML.

* update comments.

* Add samples.

* PR feedback.

* Add TestEstimatorCore, samples and misc PR feedback.

* update docs.

* update entry points.

Author: codemzs

docs/api-reference/io-time-series-ssa-forecast.md

@@ -0,0 +1,5 @@
+### Input and Output Columns
+There is only one input column.
+The input column must be <xref:System.Single> where a <xref:System.Single> value indicates a value at a timestamp in the time series.
+
+It produces either just one vector of forecasted values or three vectors: a vector of forecasted values, a vector of confidence lower bounds and a vector of confidence upper bounds.

docs/samples/Microsoft.ML.Samples/Dynamic/Transforms/TimeSeries/DetectAnomalyBySrCnn.cs

@@ -40,7 +40,7 @@ public static void Example()
             ITransformer model = ml.Transforms.DetectAnomalyBySrCnn(outputColumnName, inputColumnName, 16, 5, 5, 3, 8, 0.35).Fit(dataView);
 
             // Create a time series prediction engine from the model.
-            var engine = model.CreateTimeSeriesPredictionFunction<TimeSeriesData, SrCnnAnomalyDetection>(ml);
+            var engine = model.CreateTimeSeriesEngine<TimeSeriesData, SrCnnAnomalyDetection>(ml);
 
             Console.WriteLine($"{outputColumnName} column obtained post-transformation.");
             Console.WriteLine("Data\tAlert\tScore\tMag");

docs/samples/Microsoft.ML.Samples/Dynamic/Transforms/TimeSeries/DetectChangePointBySsa.cs

@@ -57,7 +57,7 @@ public static void Example()
             ITransformer model = ml.Transforms.DetectChangePointBySsa(outputColumnName, inputColumnName, confidence, changeHistoryLength, TrainingSize, SeasonalitySize + 1).Fit(dataView);
 
             // Create a prediction engine from the model for feeding new data.
-            var engine = model.CreateTimeSeriesPredictionFunction<TimeSeriesData, ChangePointPrediction>(ml);
+            var engine = model.CreateTimeSeriesEngine<TimeSeriesData, ChangePointPrediction>(ml);
 
             // Start streaming new data points with no change point to the prediction engine.
             Console.WriteLine($"Output from ChangePoint predictions on new data:");
@@ -99,7 +99,7 @@ public static void Example()
                 model = ml.Model.Load(file, out DataViewSchema schema);
 
             // We must create a new prediction engine from the persisted model.
-            engine = model.CreateTimeSeriesPredictionFunction<TimeSeriesData, ChangePointPrediction>(ml);
+            engine = model.CreateTimeSeriesEngine<TimeSeriesData, ChangePointPrediction>(ml);
 
             // Run predictions on the loaded model.
             for (int i = 0; i < 5; i++)

docs/samples/Microsoft.ML.Samples/Dynamic/Transforms/TimeSeries/DetectChangePointBySsaStream.cs

@@ -57,7 +57,7 @@ public static void Example()
             ITransformer model = ml.Transforms.DetectChangePointBySsa(outputColumnName, inputColumnName, confidence, changeHistoryLength, TrainingSize, SeasonalitySize + 1).Fit(dataView);
 
             // Create a prediction engine from the model for feeding new data.
-            var engine = model.CreateTimeSeriesPredictionFunction<TimeSeriesData, ChangePointPrediction>(ml);
+            var engine = model.CreateTimeSeriesEngine<TimeSeriesData, ChangePointPrediction>(ml);
 
             // Start streaming new data points with no change point to the prediction engine.
             Console.WriteLine($"Output from ChangePoint predictions on new data:");
@@ -103,7 +103,7 @@ public static void Example()
                 model = ml.Model.Load(stream, out DataViewSchema schema);
 
             // We must create a new prediction engine from the persisted model.
-            engine = model.CreateTimeSeriesPredictionFunction<TimeSeriesData, ChangePointPrediction>(ml);
+            engine = model.CreateTimeSeriesEngine<TimeSeriesData, ChangePointPrediction>(ml);
 
             // Run predictions on the loaded model.
             for (int i = 0; i < 5; i++)

docs/samples/Microsoft.ML.Samples/Dynamic/Transforms/TimeSeries/DetectIidChangePoint.cs

@@ -56,7 +56,7 @@ public static void Example()
             ITransformer model = ml.Transforms.DetectIidChangePoint(outputColumnName, inputColumnName, 95, Size / 4).Fit(dataView);
 
             // Create a time series prediction engine from the model.
-            var engine = model.CreateTimeSeriesPredictionFunction<TimeSeriesData, ChangePointPrediction>(ml);
+            var engine = model.CreateTimeSeriesEngine<TimeSeriesData, ChangePointPrediction>(ml);
 
             Console.WriteLine($"{outputColumnName} column obtained post-transformation.");
             Console.WriteLine("Data\tAlert\tScore\tP-Value\tMartingale value");
@@ -97,7 +97,7 @@ public static void Example()
                 model = ml.Model.Load(file, out DataViewSchema schema);
 
             // Create a time series prediction engine from the checkpointed model.
-            engine = model.CreateTimeSeriesPredictionFunction<TimeSeriesData, ChangePointPrediction>(ml);
+            engine = model.CreateTimeSeriesEngine<TimeSeriesData, ChangePointPrediction>(ml);
             for (int index = 0; index < 8; index++)
             {
                 // Anomaly change point detection.

docs/samples/Microsoft.ML.Samples/Dynamic/Transforms/TimeSeries/DetectIidSpike.cs

@@ -48,7 +48,7 @@ public static void Example()
             ITransformer model = ml.Transforms.DetectIidSpike(outputColumnName, inputColumnName, 95, Size).Fit(dataView);
 
             // Create a time series prediction engine from the model.
-            var engine = model.CreateTimeSeriesPredictionFunction<TimeSeriesData, IidSpikePrediction>(ml);
+            var engine = model.CreateTimeSeriesEngine<TimeSeriesData, IidSpikePrediction>(ml);
 
             Console.WriteLine($"{outputColumnName} column obtained post-transformation.");
             Console.WriteLine("Data\tAlert\tScore\tP-Value");

docs/samples/Microsoft.ML.Samples/Dynamic/Transforms/TimeSeries/DetectSpikeBySsa.cs

@@ -54,7 +54,7 @@ public static void Example()
             ITransformer model = ml.Transforms.DetectSpikeBySsa(outputColumnName, inputColumnName, 95, 8, TrainingSize, SeasonalitySize + 1).Fit(dataView);
 
             // Create a prediction engine from the model for feeding new data.
-            var engine = model.CreateTimeSeriesPredictionFunction<TimeSeriesData, SsaSpikePrediction>(ml);
+            var engine = model.CreateTimeSeriesEngine<TimeSeriesData, SsaSpikePrediction>(ml);
 
             // Start streaming new data points with no change point to the prediction engine.
             Console.WriteLine($"Output from spike predictions on new data:");
@@ -94,7 +94,7 @@ public static void Example()
                 model = ml.Model.Load(file, out DataViewSchema schema);
 
             // We must create a new prediction engine from the persisted model.
-            engine = model.CreateTimeSeriesPredictionFunction<TimeSeriesData, SsaSpikePrediction>(ml);
+            engine = model.CreateTimeSeriesEngine<TimeSeriesData, SsaSpikePrediction>(ml);
 
             // Run predictions on the loaded model.
             for (int i = 0; i < 5; i++)

docs/samples/Microsoft.ML.Samples/Dynamic/Transforms/TimeSeries/Forecasting.cs

@@ -1,8 +1,8 @@
 using System;
 using System.Collections.Generic;
+using System.IO;
 using Microsoft.ML;
 using Microsoft.ML.Transforms.TimeSeries;
-using Microsoft.ML.TimeSeries;
 
 namespace Samples.Dynamic
 {
@@ -16,8 +16,7 @@ public static void Example()
             // as well as the source of randomness.
             var ml = new MLContext();
 
-            // Generate sample series data with a recurring pattern
-            const int SeasonalitySize = 5;
+            // Generate sample series data with a recurring pattern.
             var data = new List<TimeSeriesData>()
             {
                 new TimeSeriesData(0),
@@ -44,43 +43,58 @@ public static void Example()
 
             // Setup arguments.
             var inputColumnName = nameof(TimeSeriesData.Value);
+            var outputColumnName = nameof(ForecastResult.Forecast);
 
             // Instantiate the forecasting model.
-            var model = ml.Forecasting.AdaptiveSingularSpectrumSequenceModeler(inputColumnName, data.Count, SeasonalitySize + 1, SeasonalitySize,
-                1, AdaptiveSingularSpectrumSequenceModeler.RankSelectionMethod.Exact, null, SeasonalitySize / 2, false, false);
+            var model = ml.Forecasting.ForecastBySsa(outputColumnName, inputColumnName, 5, 11, data.Count, 5);
 
             // Train.
-            model.Train(dataView);
+            var transformer = model.Fit(dataView);
 
             // Forecast next five values.
-            var forecast = model.Forecast(5);
+            var forecastEngine = transformer.CreateTimeSeriesEngine<TimeSeriesData, ForecastResult>(ml);
+            var forecast = forecastEngine.Predict();
+
             Console.WriteLine($"Forecasted values:");
-            Console.WriteLine("[{0}]", string.Join(", ", forecast));
+            Console.WriteLine("[{0}]", string.Join(", ", forecast.Forecast));
             // Forecasted values:
-            // [2.452744, 2.589339, 2.729183, 2.873005, 3.028931]
+            // [1.977226, 1.020494, 1.760543, 3.437509, 4.266461]
 
             // Update with new observations.
-            dataView = ml.Data.LoadFromEnumerable(new List<TimeSeriesData>() { new TimeSeriesData(0), new TimeSeriesData(0), new TimeSeriesData(0), new TimeSeriesData(0) });
-            model.Update(dataView);
+            forecastEngine.Predict(new TimeSeriesData(0));
+            forecastEngine.Predict(new TimeSeriesData(0));
+            forecastEngine.Predict(new TimeSeriesData(0));
+            forecastEngine.Predict(new TimeSeriesData(0));
 
             // Checkpoint.
-            ml.Model.SaveForecastingModel(model, "model.zip");
+            forecastEngine.CheckPoint(ml, "model.zip");
 
             // Load the checkpointed model from disk.
-            var modelCopy = ml.Model.LoadForecastingModel<float>("model.zip");
+            // Load the model.
+            ITransformer modelCopy;
+            using (var file = File.OpenRead("model.zip"))
+                modelCopy = ml.Model.Load(file, out DataViewSchema schema);
+
+            // We must create a new prediction engine from the persisted model.
+            var forecastEngineCopy = modelCopy.CreateTimeSeriesEngine<TimeSeriesData, ForecastResult>(ml);
 
             // Forecast with the checkpointed model loaded from disk.
-            forecast = modelCopy.Forecast(5);
-            Console.WriteLine("[{0}]", string.Join(", ", forecast));
-            // [0.8681176, 0.8185108, 0.8069275, 0.84405, 0.9455081]
+            forecast = forecastEngineCopy.Predict();
+            Console.WriteLine("[{0}]", string.Join(", ", forecast.Forecast));
+            // [1.791331, 1.255525, 0.3060154, -0.200446, 0.5657795]
 
             // Forecast with the original model(that was checkpointed to disk).
-            forecast = model.Forecast(5);
-            Console.WriteLine("[{0}]", string.Join(", ", forecast));
-            // [0.8681176, 0.8185108, 0.8069275, 0.84405, 0.9455081]
+            forecast = forecastEngine.Predict();
+            Console.WriteLine("[{0}]", string.Join(", ", forecast.Forecast));
+            // [1.791331, 1.255525, 0.3060154, -0.200446, 0.5657795]
 
         }
 
+        class ForecastResult
+        {
+            public float[] Forecast { get; set; }
+        }
+
         class TimeSeriesData
         {
             public float Value;

docs/samples/Microsoft.ML.Samples/Dynamic/Transforms/TimeSeries/ForecastingWithConfidenceInterval.cs

@@ -2,7 +2,7 @@
 using System.Collections.Generic;
 using Microsoft.ML;
 using Microsoft.ML.Transforms.TimeSeries;
-using Microsoft.ML.TimeSeries;
+using System.IO;
 
 namespace Samples.Dynamic
 {
@@ -16,8 +16,7 @@ public static void Example()
             // as well as the source of randomness.
             var ml = new MLContext();
 
-            // Generate sample series data with a recurring pattern
-            const int SeasonalitySize = 5;
+            // Generate sample series data with a recurring pattern.
             var data = new List<TimeSeriesData>()
             {
                 new TimeSeriesData(0),
@@ -44,50 +43,58 @@ public static void Example()
 
             // Setup arguments.
             var inputColumnName = nameof(TimeSeriesData.Value);
+            var outputColumnName = nameof(ForecastResult.Forecast);
 
-            // Instantiate forecasting model.
-            var model = ml.Forecasting.AdaptiveSingularSpectrumSequenceModeler(inputColumnName, data.Count, SeasonalitySize + 1, SeasonalitySize,
-                1, AdaptiveSingularSpectrumSequenceModeler.RankSelectionMethod.Exact, null, SeasonalitySize / 2, shouldComputeForecastIntervals: true, false);
+            // Instantiate the forecasting model.
+            var model = ml.Forecasting.ForecastBySsa(outputColumnName, inputColumnName, 5, 11, data.Count, 5,
+                confidenceLevel: 0.95f,
+                forcastingConfidentLowerBoundColumnName: "ConfidenceLowerBound",
+                forcastingConfidentUpperBoundColumnName: "ConfidenceUpperBound");
 
             // Train.
-            model.Train(dataView);
-
-            // Forecast next five values with confidence internal.
-            float[] forecast;
-            float[] confidenceIntervalLowerBounds;
-            float[] confidenceIntervalUpperBounds;
-            model.ForecastWithConfidenceIntervals(5, out forecast, out confidenceIntervalLowerBounds, out confidenceIntervalUpperBounds);
-            PrintForecastValuesAndIntervals(forecast, confidenceIntervalLowerBounds, confidenceIntervalUpperBounds);
+            var transformer = model.Fit(dataView);
+
+            // Forecast next five values.
+            var forecastEngine = transformer.CreateTimeSeriesEngine<TimeSeriesData, ForecastResult>(ml);
+            var forecast = forecastEngine.Predict();
+
+            PrintForecastValuesAndIntervals(forecast.Forecast, forecast.ConfidenceLowerBound, forecast.ConfidenceUpperBound);
             // Forecasted values:
-            // [2.452744, 2.589339, 2.729183, 2.873005, 3.028931]
+            // [1.977226, 1.020494, 1.760543, 3.437509, 4.266461]
             // Confidence intervals:
-            // [-0.2235315 - 5.12902] [-0.08777174 - 5.266451] [0.05076938 - 5.407597] [0.1925406 - 5.553469] [0.3469928 - 5.71087]
+            // [0.3451088 - 3.609343] [-0.7967533 - 2.83774] [-0.058467 - 3.579552] [1.61505 - 5.259968] [2.349299 - 6.183623]
 
             // Update with new observations.
-            dataView = ml.Data.LoadFromEnumerable(new List<TimeSeriesData>() { new TimeSeriesData(0), new TimeSeriesData(0), new TimeSeriesData(0), new TimeSeriesData(0) });
-            model.Update(dataView);
+            forecastEngine.Predict(new TimeSeriesData(0));
+            forecastEngine.Predict(new TimeSeriesData(0));
+            forecastEngine.Predict(new TimeSeriesData(0));
+            forecastEngine.Predict(new TimeSeriesData(0));
 
             // Checkpoint.
-            ml.Model.SaveForecastingModel(model, "model.zip");
+            forecastEngine.CheckPoint(ml, "model.zip");
 
             // Load the checkpointed model from disk.
-            var modelCopy = ml.Model.LoadForecastingModel<float>("model.zip");
+            // Load the model.
+            ITransformer modelCopy;
+            using (var file = File.OpenRead("model.zip"))
+                modelCopy = ml.Model.Load(file, out DataViewSchema schema);
+
+            // We must create a new prediction engine from the persisted model.
+            var forecastEngineCopy = modelCopy.CreateTimeSeriesEngine<TimeSeriesData, ForecastResult>(ml);
 
             // Forecast with the checkpointed model loaded from disk.
-            modelCopy.ForecastWithConfidenceIntervals(5, out forecast, out confidenceIntervalLowerBounds, out confidenceIntervalUpperBounds);
-            PrintForecastValuesAndIntervals(forecast, confidenceIntervalLowerBounds, confidenceIntervalUpperBounds);
-            // Forecasted values:
-            // [0.8681176, 0.8185108, 0.8069275, 0.84405, 0.9455081]
+            forecast = forecastEngineCopy.Predict();
+            PrintForecastValuesAndIntervals(forecast.Forecast, forecast.ConfidenceLowerBound, forecast.ConfidenceUpperBound);
+            // [1.791331, 1.255525, 0.3060154, -0.200446, 0.5657795]
             // Confidence intervals:
-            // [-1.808158 - 3.544394] [-1.8586 - 3.495622] [-1.871486 - 3.485341] [-1.836414 - 3.524514] [-1.736431 - 3.627447]
+            // [0.1592142 - 3.423448] [-0.5617217 - 3.072772] [-1.512994 - 2.125025] [-2.022905 - 1.622013] [-1.351382 - 2.482941]
 
             // Forecast with the original model(that was checkpointed to disk).
-            model.ForecastWithConfidenceIntervals(5, out forecast, out confidenceIntervalLowerBounds, out confidenceIntervalUpperBounds);
-            PrintForecastValuesAndIntervals(forecast, confidenceIntervalLowerBounds, confidenceIntervalUpperBounds);
-            // Forecasted values:
-            // [0.8681176, 0.8185108, 0.8069275, 0.84405, 0.9455081]
+            forecast = forecastEngine.Predict();
+            PrintForecastValuesAndIntervals(forecast.Forecast, forecast.ConfidenceLowerBound, forecast.ConfidenceUpperBound);
+            // [1.791331, 1.255525, 0.3060154, -0.200446, 0.5657795]
             // Confidence intervals:
-            // [-1.808158 - 3.544394] [-1.8586 - 3.495622] [-1.871486 - 3.485341] [-1.836414 - 3.524514] [-1.736431 - 3.627447]
+            // [0.1592142 - 3.423448] [-0.5617217 - 3.072772] [-1.512994 - 2.125025] [-2.022905 - 1.622013] [-1.351382 - 2.482941]
         }
 
         static void PrintForecastValuesAndIntervals(float[] forecast, float[] confidenceIntervalLowerBounds, float[] confidenceIntervalUpperBounds)
@@ -100,6 +107,13 @@ static void PrintForecastValuesAndIntervals(float[] forecast, float[] confidence
             Console.WriteLine();
         }
 
+        class ForecastResult
+        {
+            public float[] Forecast { get; set; }
+            public float[] ConfidenceLowerBound { get; set; }
+            public float[] ConfidenceUpperBound { get; set; }
+        }
+
         class TimeSeriesData
         {
             public float Value;

docs/samples/Microsoft.ML.Samples/Program.cs

@@ -1,5 +1,6 @@
 using System;
 using System.Reflection;
+using Samples.Dynamic;
 
 namespace Microsoft.ML.Samples
 {