Add DetectSeasonality as a Helper function in TimeSeries ExtensionDialog

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

@@ -0,0 +1,56 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using Microsoft.ML;
+using Microsoft.ML.TimeSeries;
+
+namespace Samples.Dynamic
+{
+    public static class DetectSeasonality
+    {
+        public static void Example()
+        {
+            /* Create a new ML context, for ML.NET operations. It can be used for
+             exception tracking and logging, as well as the source of randomness.*/
+            var mlContext = new MLContext();
+
+            // Create a seasonal data as input for DetectSeasonality.
+            var dataView = mlContext.Data.LoadFromEnumerable(GetPointsWithSeasonality());
+
+            /* Two option parameters:
+             * seasonalityWindowSize: Default value is -1. When set to -1, use the whole input to fit model; 
+             * when set to a positive integer, only the first windowSize number of values will be considered.
+             * randomnessThreshold: Randomness threashold that specifies how confidence the input values follows 
+             * a predictable pattern recurring over an interval as seasonal data. By default, it is set as 2.81
+             * for 99.5% confidence. The higher the threshold is set, the more strict recurring pattern the 
+             * input values should follow to be determined as seasonal data.
+             */
+            int period = mlContext.AnomalyDetection.DetectSeasonality(
+                dataView,
+                nameof(TimeSeriesData.Value),
+                seasonalityWindowSize: 40);
+
+            // Print the Seasonality Period result.
+            Console.WriteLine($"Seasonality Period: #{period}");
+        }
+
+        private static IEnumerable<TimeSeriesData> GetPointsWithSeasonality()
+        {
+            return new List<double>() {18.004, 87.401, 87.411, 18.088, 18.017, 87.759, 33.996, 18.043, 87.853, 18.364, 18.004, 86.992, 87.555,
+                18.088, 18.029, 87.906, 87.471, 18.039, 18.099, 87.403, 18.030, 72.991, 87.804, 18.381, 18.016, 87.145, 87.771,
+                18.029, 18.084, 87.976, 34.913, 18.064, 18.302, 87.723, 18.001, 86.401, 87.344, 18.295, 18.002, 87.793,
+                87.531, 18.055, 18.005, 87.947, 18.003, 72.743, 87.722, 18.142 }.Select(t => new TimeSeriesData(t));
+        }
+
+        private class TimeSeriesData
+        {
+            public double Value;
+
+            public TimeSeriesData(double value)
+            {
+                Value = value;
+            }
+        }
+
+    }
+}

src/Microsoft.ML.Data/Transforms/NormalizeColumnDbl.cs

@@ -597,6 +597,7 @@ internal static void GetMedianSoFar(in double num, ref double median, ref MaxHea
     /// It tracks median values of non-sparse values (vCount).
     /// NaNs are ignored when updating min and max.
     /// </summary>
+    [BestFriend]
     internal sealed class MedianDblAggregator : IColumnAggregator<double>
     {
         private MedianAggregatorUtils.MaxHeap<double> _belowMedianHeap;
@@ -1213,7 +1214,7 @@ private void GetResult(ref TFloat input, ref TFloat value)
                     }
 
                     public override NormalizingTransformer.NormalizerModelParametersBase GetNormalizerModelParams()
-                         => new NormalizingTransformer.BinNormalizerModelParameters<TFloat>(ImmutableArray.Create(_binUpperBounds), _den,_offset);
+                         => new NormalizingTransformer.BinNormalizerModelParameters<TFloat>(ImmutableArray.Create(_binUpperBounds), _den, _offset);
                 }
 
                 public sealed class ImplVec : BinColumnFunction

src/Microsoft.ML.TimeSeries/ExtensionsCatalog.cs

@@ -210,6 +210,55 @@ public static RootCause LocalizeRootCause(this AnomalyDetectionCatalog catalog,
             return dst;
         }
 
+        /// <summary>
+        /// <para>
+        /// In time series data, seasonality (or periodicity) is the presence of variations that occur at specific regular intervals,
+        /// such as weekly, monthly, or quarterly.
+        /// </para>
+        /// <para>
+        /// This method detects this predictable interval (or period) by adopting techniques of fourier analysis.
+        /// Assuming the input values have the same time interval (e.g., sensor data collected at every second ordered by timestamps),
+        /// this method takes a list of time-series data, and returns the regular period for the input seasonal data,
+        /// if a predictable fluctuation or pattern can be found that recurs or repeats over this period throughout the input values.
+        /// </para>
+        /// <para>
+        /// Returns -1 if no such pattern is found, that is, the input values do not follow a seasonal fluctuation.
+        /// </para>
+        /// </summary>
+        /// <param name="catalog">The detect seasonality catalog.</param>
+        /// <param name="input">Input DataView.The data is an instance of <see cref="Microsoft.ML.IDataView"/>.</param>
+        /// <param name="inputColumnName">Name of column to process. The column data must be <see cref="System.Double"/>.</param>
+        /// <param name="seasonalityWindowSize">An upper bound on the number of values to be considered in the input values.
+        /// When set to -1, use the whole input to fit model; when set to a positive integer, only the first windowSize number
+        /// of values will be considered. Default value is -1.</param>
+        /// <param name="randomnessThreshold"><a href ="https://en.wikipedia.org/wiki/Correlogram">Randomness flutuation threashold</a>
+        /// that specifies how confidence the input values follows a predictable pattern recurring over an interval as seasonal data.
+        /// By default, it is set as 2.81: <a href="https://en.wikipedia.org/wiki/Student%27s_t-distribution">two-sided t-distribution
+        /// for 99.5% confidence interval</a> with infinit degree of freedom.
+        /// The higher the threshold is set, the more strict recurring pattern the input values should follow to be determined as
+        /// seasonal data.
+        /// </param>
+        /// <returns>The regular interval for the input as seasonal data, otherwise return -1.</returns>
+        /// <example>
+        /// <format type="text/markdown">
+        /// <![CDATA[
+        /// [!code-csharp[LocalizeRootCause](~/../docs/samples/docs/samples/Microsoft.ML.Samples/Dynamic/Transforms/TimeSeries/DetectSeasonality.cs)]
+        /// ]]>
+        /// </format>
+        /// </example>
+        public static int DetectSeasonality(
+             this AnomalyDetectionCatalog catalog,
+             IDataView input,
+             string inputColumnName,
+             int seasonalityWindowSize = -1,
+             double randomnessThreshold = 2.81)
+         => new SeasonalityDetector().DetectSeasonality(
+             CatalogUtils.GetEnvironment(catalog),
+             input,
+             inputColumnName,
+             seasonalityWindowSize,
+             randomnessThreshold);
+
         private static void CheckRootCauseInput(IHostEnvironment host, RootCauseLocalizationInput src)
         {
             host.CheckUserArg(src.Slices.Count >= 1, nameof(src.Slices), "Must has more than one item");