Add deseasonality in SrCnnEntireAnomalyDetect

src/Microsoft.ML.TimeSeries/ExtensionsCatalog.cs

@@ -167,6 +167,7 @@ public static SrCnnAnomalyEstimator DetectAnomalyBySrCnn(this TransformsCatalog
         /// When set to AnomalyAndMargin, the output vector would be a 7-element Double vector of (IsAnomaly, AnomalyScore, Mag, ExpectedValue, BoundaryUnit, UpperBoundary, LowerBoundary).
         /// The RawScore is output by SR to determine whether a point is an anomaly or not, under AnomalyAndMargin mode, when a point is an anomaly, an AnomalyScore will be calculated according to sensitivity setting.
         /// Default value is AnomalyOnly.</param>
+        /// <param name="period">The period of the data to be detected. If the data has a circular pattern, set this parameter to the length of one period, otherwise 0 which indicates that there is no circular pattern. Default value is 0.</param>
         /// <example>
         /// <format type="text/markdown">
         /// <![CDATA[
@@ -175,8 +176,8 @@ public static SrCnnAnomalyEstimator DetectAnomalyBySrCnn(this TransformsCatalog
         /// </format>
         /// </example>
         public static IDataView DetectEntireAnomalyBySrCnn(this AnomalyDetectionCatalog catalog, IDataView input, string outputColumnName, string inputColumnName,
-            double threshold = 0.3, int batchSize = 1024, double sensitivity = 99, SrCnnDetectMode detectMode = SrCnnDetectMode.AnomalyOnly)
-            => new SrCnnEntireAnomalyDetector(CatalogUtils.GetEnvironment(catalog), input, inputColumnName, outputColumnName, threshold, batchSize, sensitivity, detectMode);
+            double threshold = 0.3, int batchSize = 1024, double sensitivity = 99, SrCnnDetectMode detectMode = SrCnnDetectMode.AnomalyOnly, int period = 0)
+            => new SrCnnEntireAnomalyDetector(CatalogUtils.GetEnvironment(catalog), input, inputColumnName, outputColumnName, threshold, batchSize, sensitivity, detectMode, period);
 
         /// <summary>
         /// Create <see cref="RootCause"/>, which localizes root causes using decision tree algorithm.

src/Microsoft.ML.TimeSeries/STL/BackendStructureBase.cs

@@ -0,0 +1,111 @@
+using System;
+using System.Collections.Generic;
+using System.Text;
+
+namespace Microsoft.ML.TimeSeries
+{
+    public enum TimeSeriesInfoKind
+    {
+        /// <summary>
+        /// (single-time series) the outliers of a single time series
+        /// </summary>
+        Outlier,
+
+        /// <summary>
+        /// (single-time series) the seasonal signal of a single time series
+        /// </summary>
+        Seasonal,
+
+        /// <summary>
+        /// (single-time series) the trend curve of a single time series
+        /// </summary>
+        Trend,
+
+        /// <summary>
+        /// (two-time series) the lead/lag correlation between two time series
+        /// </summary>
+        CrossCorrelation,
+
+        /// <summary>
+        /// (two-time series) the correlation of outliers from two time series
+        /// </summary>
+        OutlierCorrelation,
+
+        /// <summary>
+        /// (two-time series) the correlation of trends from two time series
+        /// </summary>
+        TrendCorrelation,
+    }
+
+    public abstract class TimeSeriesInfoBase
+    {
+        /// <summary>
+        /// each insight should be ranked, so that it can be compared with other insights.
+        /// </summary>
+        public abstract double Rank { get; set; }
+
+        /// <summary>
+        /// the description of this particular insight
+        /// </summary>
+        public abstract string Description { get; protected set; }
+
+        /// <summary>
+        /// indicate the kind of insight.
+        /// </summary>
+        public abstract TimeSeriesInfoKind Kind { get; protected set; }
+
+        /// <summary>
+        /// basic comparison function, used for quick sort.
+        /// </summary>
+        /// <param name="left">the left element</param>
+        /// <param name="right">the right element</param>
+        public static int Compare(TimeSeriesInfoBase left, TimeSeriesInfoBase right)
+        {
+            if (object.ReferenceEquals(left, right))
+                return 0;
+            if (left == null)
+                return -1;
+            if (right == null)
+                return 1;
+            return left.Rank.CompareTo(right.Rank);
+        }
+    }
+
+    /// <summary>
+    /// the characteristic of single time series.
+    /// </summary>
+    public abstract class SingleSeriesInfo : TimeSeriesInfoBase
+    {
+        /// <summary>
+        /// x-axis values of original curve
+        /// </summary>
+        public IReadOnlyList<double> X { get; protected set; }
+
+        /// <summary>
+        /// y-axis values of original curve
+        /// </summary>
+        public IReadOnlyList<double> Y { get; protected set; }
+    }
+
+    /// <summary>
+    /// the characteristic between two time series, such as the lead/lag correlation,
+    /// and the correlation of the outliers.
+    /// </summary>
+    public abstract class TwoSeriesInfo : TimeSeriesInfoBase
+    {
+        /// <summary>
+        /// x-axis values of two time series. they should be aligned.
+        /// </summary>
+        public IReadOnlyList<double> X { get; protected set; }
+
+        /// <summary>
+        /// y-axis values of first series
+        /// </summary>
+        public IReadOnlyList<double> Y1 { get; protected set; }
+
+        /// <summary>
+        /// y-axis values of second series
+        /// </summary>
+        public IReadOnlyList<double> Y2 { get; protected set; }
+    }
+}

src/Microsoft.ML.TimeSeries/STL/BasicParameters.cs

@@ -0,0 +1,30 @@
+using System;
+using System.Collections.Generic;
+using System.Text;
+
+namespace Microsoft.ML.TimeSeries
+{
+    public class BasicParameters
+    {
+        /// <summary>
+        /// the minimum length of a valid time series. a time series with length equals 2 is so trivial. when less than 2, meaningless.
+        /// </summary>
+        public const int MinTimeSeriesLength = 3;
+
+        /// <summary>
+        /// the maximum length of a valid time series. when there are too many data points, the chart will look so dense that details are lost.
+        /// this number is tuned so that the bird strike data can still preserve results.
+        /// </summary>
+        public const int MaxTimeSeriesLength = 4000;
+
+        /// <summary>
+        /// the minimum count of repeated periods. this is used for determining a noticeable seasonal signal.
+        /// </summary>
+        public const int MinPeriodRepeatCount = 3;
+
+        /// <summary>
+        /// the minimum count of regular gaps. when there are too few gaps, the time series will look odd, which will impact the seasonality analysis
+        /// </summary>
+        public const int MinRegularGap = 5;
+    }
+}

src/Microsoft.ML.TimeSeries/STL/FastLoess.cs

@@ -0,0 +1,99 @@
+using System;
+using System.Collections.Generic;
+using System.Text;
+using Microsoft.ML.Runtime;
+
+namespace Microsoft.ML.TimeSeries
+{
+    /// <summary>
+    /// this is the fast version of Loess. there are several alternatives to improve the performance. this one is an approximation approach.
+    /// the smoothing is conducted on a sample set, and then the values on the left points are assigned directly.
+    /// </summary>
+    public class FastLoess
+    {
+        /// <summary>
+        /// this class is a sampling based method, so here specifies the sample size.
+        /// </summary>
+        private static int _sampleSize = 100;
+
+        private readonly IReadOnlyList<double> _x;
+        private readonly IReadOnlyList<double> _y;
+        private readonly int _length;
+
+        private readonly Loess _smoother;
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="FastLoess"/> class.
+        /// the fast version of the Loess method. when the time series is too long, the sampling will be conducted first
+        /// to improve the performance.
+        /// </summary>
+        /// <param name="xValues">the input x-axis values</param>
+        /// <param name="yValues">the input y-axis values</param>
+        /// <param name="isTemporal">if the regression is considered to take temporal information into account. in general, this is true if we are regressing a time series, and false if we are regressing scatter plot data</param>
+        /// <param name="r">this method will provide default smoothing ratio if user did not specify</param>
+        public FastLoess(IReadOnlyList<double> xValues, IReadOnlyList<double> yValues, bool isTemporal = true, int r = -1)
+        {
+            Contracts.CheckValue(xValues, nameof(xValues));
+            Contracts.CheckValue(yValues, nameof(yValues));
+            Y = new List<double>();
+
+            if (yValues.Count < BasicParameters.MinTimeSeriesLength)
+                throw new Exception("input data structure cannot be 0-length: lowess");
+
+            _x = xValues;
+            _y = yValues;
+            _length = _y.Count;
+
+            // the sampling is not neccessary
+            if (_length <= FastLoess._sampleSize)
+            {
+                if (r == -1)
+                    _smoother = new Loess(_x, _y, isTemporal);
+                else
+                    _smoother = new Loess(_x, _y, r, isTemporal);
+            }
+            else
+            {
+                // conduct sampling based strategy, to boost the performance.
+                double step = _length * 1.0 / FastLoess._sampleSize;
+                var sampleX = new double[FastLoess._sampleSize];
+                var sampleY = new double[FastLoess._sampleSize];
+                for (int i = 0; i < FastLoess._sampleSize; i++)
+                {
+                    int index = (int)(i * step);
+                    sampleX[i] = _x[index];
+                    sampleY[i] = _y[index];
+                }
+                if (r == -1)
+                    _smoother = new Loess(sampleX, sampleY, isTemporal);
+                else
+                    _smoother = new Loess(sampleX, sampleY, r, isTemporal);
+            }
+        }
+
+        /// <summary>
+        /// the estimated y values. this is the very cool smoothing method.
+        /// </summary>
+        public List<double> Y { get; }
+
+        /// <summary>
+        /// assign the smoothing values to all the data points, not only on the sample size.
+        /// </summary>
+        public void Estimate()
+        {
+            for (int i = 0; i < _length; i++)
+            {
+                double yValue = _smoother.EstimateY(_x[i]);
+                Y.Add(yValue);
+            }
+        }
+
+        /// <summary>
+        /// estimate any y value by given any x value, event the x value is not one of the input points.
+        /// </summary>
+        public double EstimateY(double xValue)
+        {
+            return _smoother.EstimateY(xValue);
+        }
+    }
+}