kats.detectors.seasonality module¶

This module is for seasonality detection.

We provide two seasonality detector: ACFDetector and FFTDetector. ACFDetector uses autocorrelation function to find seasonality, while FFTDetector uses Fast Fourier Transform to detect seasonality.

Typical usage example:

>>> timeseries = TimeSeriesData(...)
>>> # initialize detector
>>> detector = ACFDetector(timeseries)
>>> # run detector
>>> detector.detector(diff=1, alpha = 0.01)
>>> # seasonality decomposition, returns trend, seasonal, residual term
>>> detector.remover()
>>> # plot acf and decompsition results
>>> detector.plot()
class kats.detectors.seasonality.ACFDetector(data: kats.consts.TimeSeriesData)[source]¶

Bases: kats.detectors.detector.Detector

Autocorrelation function seasonality detector.

Use acf to detect seasonality, and find out the potential cycle lengths

data¶

The input time series data from TimeSeriesData

decomposed¶

A bool indicate if we decomposed the time series into trend, seasonal and residual.

detector(lags: Optional[int] = None, diff: int = 1, alpha: Optional[float] = 0.01) → Dict[str, Any][source]¶

Detect seasonality

This method runs acf and returns if seasonality detected in the given time series and potential cycle lengths

Parameters

  • lags – Optional; int; the maximum lags we used in acf.

  • diff – Optional; int; times of diff run on timeseries to remove trend before apply acf.

  • alpha – Optional; float; significant level we use the calcualte autocorrelation confidence interval.

Returns

A dict contains

  • seasonality_presence: bool, if seasonality detected

  • seasonalities: List[int], potential seasonlities cycle length(s)

plot() → None[source]¶

Plot detection results.

Parameters

None –

Returns

None

remover(decom: Type = <class 'kats.utils.decomposition.TimeSeriesDecomposition'>, model: str = 'additive', decompose_any_way: bool = False) → Optional[Dict[str, Any]][source]¶

Remove the seasonality in the time series

Parameters

  • decom – Optional; decomposition method.

  • model – Optional; model used for decomposition.

  • decompose_any_way – Optional; bool; decompose the time series even when seasonality is not detected in the time series.

Returns

decomposition results of the decomposition method.

class kats.detectors.seasonality.FFTDetector(data: kats.consts.TimeSeriesData)[source]¶

Bases: kats.detectors.detector.Detector

Fast Fourier Transform Seasoanlity detector

Use Fast Fourier Transform to detect seasonality, and find out the potential cycle’s length.

data¶

The input time series data from TimeSeriesData.

detector(sample_spacing: float = 1.0, mad_threshold: float = 6.0) → Dict[source]¶

Detect seasonality with FFT

Parameters

  • sample_spacing – Optional; float; scaling FFT for a different time unit. I.e. for hourly time series, sample_spacing=24.0, FFT x axis will be 1/day.

  • mad_threshold – Optional; float; constant for the outlier algorithm for peak detector. The larger the value the less sensitive the outlier algorithm is.

Returns

FFT Plot with peaks, selected peaks, and outlier boundary line.

get_fft(sample_spacing: float = 1.0) → pandas.core.frame.DataFrame[source]¶

Computes FFT

Parameters

sample_spacing – Optional; scaling FFT for a different time unit. I.e. for hourly time series, sample_spacing=24.0 FFT x axis will be 1/day.

Returns

DataFrame with columns ‘freq’ and ‘ampl’.

get_fft_peaks(fft: pandas.core.frame.DataFrame, mad_threshold: float = 6.0) → Tuple[float, List[float], List[float]][source]¶
Computes peaks in fft, selects the highest peaks (outliers) and

removes the harmonics (multiplies of the base harmonics found)

Parameters

  • fft – FFT computed by FFTDetector.get_fft

  • sample_spacing – Optional; scaling FFT for a different time unit. I.e. for hourly time series, sample_spacing=24.0 FFT x axis will be 1/day.

  • mad_threshold – Optional; constant for the outlier algorithm for peak detector. The larger the value the less sensitive the outlier algorithm is.

Returns

outlier threshold, peaks, selected peaks.

plot(time_unit: str, sample_spacing: float = 1.0, title: str = 'FFT', mad_threshold: float = 6.0) → plotly.graph_objs._figure.Figure[source]¶

Plots an FFT plot as a plotly figure

Parameters

  • time_unit – string containing the unit of time (displayed on x axis). E.g. ‘Hour’.

  • sample_spacing – Optional; scaling FFT for a different time unit. I.e. for hourly time series, sample_spacing=24.0, FFT x axis will be 1/day.

  • title – Optional; title of the plot.

  • mad_threshold – Optional; constant for the outlier algorithm for peak detector. The larger the value the less sensitive the outlier algorithm is.

Returns

FFT Plot with peaks, selected peaks, and outlier boundary line.

plot_fft(time_unit: str, sample_spacing: float = 1.0, title: str = 'FFT', mad_threshold: float = 6.0) → plotly.graph_objs._figure.Figure[source]¶

Plots an FFT plot as a plotly figure

Parameters

  • time_unit – string containing the unit of time (displayed on x axis). E.g. ‘Hour’

  • sample_spacing – Optional; scaling FFT for a different time unit. I.e. for hourly time series, sample_spacing=24.0, FFT x axis will be 1/day

  • title – Optional; title of the plot

  • mad_threshold – Optional; constant for the outlier algorithm for peak detector. The larger the value the less sensitive the outlier algorithm is.

Returns

FFT Plot with peaks, selected peaks, and outlier boundary line