series_periods_detect()

Learn how to use the series_periods_detect() function to find the most significant periods that exist in a time series.

Finds the most significant periods within a time series.

The series_periods_detect() function is useful for detecting periodic patterns in data, such as daily, weekly, or monthly cycles.

Syntax

series_periods_detect(series, min_period, max_period, num_periods)

Parameters

NameTypeRequiredDescription
seriesdynamic✔️An array of numeric values, typically the resulting output of the make-series or make_list operators.
min_periodreal✔️The minimal period length for which to search.
max_periodreal✔️The maximal period length for which to search.
num_periodslong✔️The maximum number of periods to return. This number is the length of the output dynamic arrays.

Returns

The function returns a table with two columns:

  • periods: A dynamic array containing the periods found, in units of the bin size, ordered by their scores.
  • scores: A dynamic array containing values between 0 and 1. Each array measures the significance of a period in its respective position in the periods array.

Example

The following query embeds a snapshot of application traffic for one month. The amount of traffic is aggregated twice a day, meaning the bin size is 12 hours. The query produces a line chart clearly showing a pattern in the data.

print y=dynamic([80, 139, 87, 110, 68, 54, 50, 51, 53, 133, 86, 141, 97, 156, 94, 149, 95, 140, 77, 61, 50, 54, 47, 133, 72, 152, 94, 148, 105, 162, 101, 160, 87, 63, 53, 55, 54, 151, 103, 189, 108, 183, 113, 175, 113, 178, 90, 71, 62, 62, 65, 165, 109, 181, 115, 182, 121, 178, 114, 170])
| project x=range(1, array_length(y), 1), y  
| render linechart

Series periods.

You can run the series_periods_detect() function on the same series to identify the recurring patterns. The function searches for patterns in the specified period range and returns two values. The first value indicates a detected pattern that is 14 point long with a score of approximately .84. The other value is zero that indicates no additional pattern was found.

print y=dynamic([80, 139, 87, 110, 68, 54, 50, 51, 53, 133, 86, 141, 97, 156, 94, 149, 95, 140, 77, 61, 50, 54, 47, 133, 72, 152, 94, 148, 105, 162, 101, 160, 87, 63, 53, 55, 54, 151, 103, 189, 108, 183, 113, 175, 113, 178, 90, 71, 62, 62, 65, 165, 109, 181, 115, 182, 121, 178, 114, 170])
| project x=range(1, array_length(y), 1), y  
| project series_periods_detect(y, 0.0, 50.0, 2)

Output

series_periods_detect_y_periodsseries_periods_detect_y_periods_scores
[14, 0][0.84, 0]

The value in series_periods_detect_y_periods_scores is truncated.

Related content