TimeSeriesCatalog.DetectSeasonality Method

Definition

Namespace:

Microsoft.ML

Assembly:

Microsoft.ML.TimeSeries.dll

Package:

Microsoft.ML.TimeSeries v3.0.1

In time series data, seasonality (or periodicity) is the presence of variations that occur at specific regular intervals, such as weekly, monthly, or quarterly.

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.

Returns -1 if no such pattern is found, that is, the input values do not follow a seasonal fluctuation.

public static int DetectSeasonality (this Microsoft.ML.AnomalyDetectionCatalog catalog, Microsoft.ML.IDataView input, string inputColumnName, int seasonalityWindowSize = -1, double randomnessThreshold = 0.95);

static member DetectSeasonality : Microsoft.ML.AnomalyDetectionCatalog * Microsoft.ML.IDataView * string * int * double -> int

<Extension()>
Public Function DetectSeasonality (catalog As AnomalyDetectionCatalog, input As IDataView, inputColumnName As String, Optional seasonalityWindowSize As Integer = -1, Optional randomnessThreshold As Double = 0.95) As Integer

Parameters

catalog

AnomalyDetectionCatalog

The detect seasonality catalog.

input

IDataView

Input DataView.The data is an instance of IDataView.

inputColumnName

String

Name of column to process. The column data must be Double.

seasonalityWindowSize

Int32

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.

randomnessThreshold

Double

Randomness threshold that specifies how confidently the input values follow a predictable pattern recurring as seasonal data. The range is between [0, 1]. By default, it is set as 0.95.

Returns

Int32

The regular interval for the input as seasonal data, otherwise return -1.

Examples

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: y = sin(2 * Pi + x)
            var seasonalData = Enumerable.Range(0, 100).Select(x => new TimeSeriesData(Math.Sin(2 * Math.PI + x)));

            // Load the input data as a DataView.
            var dataView = mlContext.Data.LoadFromEnumerable(seasonalData);

            /* 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 threshold that specifies how confidence the input values follows 
             * a predictable pattern recurring as seasonal data. By default, it is set as 0.99. 
             * 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 class TimeSeriesData
        {
            public double Value;

            public TimeSeriesData(double value)
            {
                Value = value;
            }
        }

    }
}