Implementation:Rapidsai Cuml Seasonality Test
| Knowledge Sources | |
|---|---|
| Domains | Machine_Learning, Time_Series, Stationarity |
| Last Updated | 2026-02-08 12:00 GMT |
Overview
Performs the Wang, Smith, and Hyndman seasonality test to determine whether a time series (or batch of time series) requires seasonal differencing.
Description
The seasonality.py module implements a heuristic test for seasonal stationarity based on the method of Wang, Smith, and Hyndman. It decomposes each time series using STL (Seasonal-Trend decomposition using LOESS) from statsmodels, then computes a strength-of-seasonality heuristic:
heuristic = max(0, min(1, 1 - Var(residual) / Var(residual + seasonal)))
If this heuristic exceeds a threshold (default 0.64), the series is deemed to need seasonal differencing.
The module exposes two functions:
seas_test(public) -- The main entry point. Accepts device or host arrays, converts to host for STL decomposition, runs the test for each series in the batch, and returns a device array of boolean results.python_seas_test(internal) -- The Python prototype that performs the actual STL decomposition and heuristic computation. This is intended to be ported to CUDA in the future.
This function is used internally by cuML's AutoARIMA to decide the seasonal differencing order D.
Usage
Use this function when you need to determine whether seasonal differencing should be applied to one or more time series before fitting an ARIMA model. It is typically called as part of the automatic model selection pipeline in AutoARIMA.
Code Reference
Source Location
- Repository: Rapidsai_Cuml
- File:
python/cuml/cuml/tsa/seasonality.py
Signature
def seas_test(y, s, convert_dtype=True) -> CumlArray
# Internal prototype:
def python_seas_test(y, batch_size, n_obs, s, threshold=0.64)
Import
from cuml.tsa.seasonality import seas_test
I/O Contract
Inputs -- seas_test
| Name | Type | Required | Description |
|---|---|---|---|
| y | dataframe or array-like (device or host) | Yes | Time series data with each series in a column, shape (n_obs, batch_size). Accepts cuDF DataFrame, cuDF Series, NumPy ndarray, Numba device ndarray, CuPy array.
|
| s | int | Yes | Seasonal period. Must be greater than 1. |
| convert_dtype | bool | No | If True (default), convert input to float32.
|
Inputs -- python_seas_test (internal)
| Name | Type | Required | Description |
|---|---|---|---|
| y | array of shape (n_obs, batch_size) | Yes | Time series data (host array). |
| batch_size | int | Yes | Number of series in the batch. |
| n_obs | int | Yes | Number of observations per series. |
| s | int | Yes | Seasonal period. |
| threshold | float | No | Seasonality strength threshold. Default 0.64.
|
Outputs
| Name | Type | Description |
|---|---|---|
| stationarity | CumlArray of bool, shape (batch_size,) | For each series, True if the series needs seasonal differencing, False otherwise.
|
Usage Examples
import numpy as np
from cuml.tsa.seasonality import seas_test
# Create synthetic seasonal data (2 series, 120 observations each)
t = np.arange(120)
series1 = np.sin(2 * np.pi * t / 12) + np.random.randn(120) * 0.1
series2 = np.random.randn(120) # no seasonality
y = np.column_stack([series1, series2]).astype(np.float32)
# Test for seasonal differencing need with period=12
result = seas_test(y, s=12)
print(result) # [True, False] - first series is seasonal