statsmodels.tsa.forecasting.stl.STLForecast¶

class statsmodels.tsa.forecasting.stl.STLForecast(endog, model, *, model_kwargs=None, period=None, seasonal=7, trend=None, low_pass=None, seasonal_deg=1, trend_deg=1, low_pass_deg=1, robust=False, seasonal_jump=1, trend_jump=1, low_pass_jump=1)[source]¶

Model-based forecasting using STL to remove seasonality

Forecasts are produced by first subtracting the seasonality estimated using STL, then forecasting the deseasonalized data using a time-series model, for example, ARIMA.

Parameters:¶

endogarray_like

Data to be decomposed. Must be squeezable to 1-d.

modelModel

The model used to forecast endog after the seasonality has been removed using STL

model_kwargsdict[str, Any]

Any additional arguments needed to initialized the model using the residuals produced by subtracting the seasonality.

period{int, None}, optional

Periodicity of the sequence. If None and endog is a pandas Series or DataFrame, attempts to determine from endog. If endog is a ndarray, period must be provided.

seasonalint, optional

Length of the seasonal smoother. Must be an odd integer, and should normally be >= 7 (default).

trend{int, None}, optional

Length of the trend smoother. Must be an odd integer. If not provided uses the smallest odd integer greater than 1.5 * period / (1 - 1.5 / seasonal), following the suggestion in the original implementation.

low_pass{int, None}, optional

Length of the low-pass filter. Must be an odd integer >=3. If not provided, uses the smallest odd integer > period.

seasonal_degint, optional

Degree of seasonal LOESS. 0 (constant) or 1 (constant and trend).

trend_degint, optional

Degree of trend LOESS. 0 (constant) or 1 (constant and trend).

low_pass_degint, optional

Degree of low pass LOESS. 0 (constant) or 1 (constant and trend).

robustbool, optional

Flag indicating whether to use a weighted version that is robust to some forms of outliers.

seasonal_jumpint, optional

Positive integer determining the linear interpolation step. If larger than 1, the LOESS is used every seasonal_jump points and linear interpolation is between fitted points. Higher values reduce estimation time.

trend_jumpint, optional

Positive integer determining the linear interpolation step. If larger than 1, the LOESS is used every trend_jump points and values between the two are linearly interpolated. Higher values reduce estimation time.

low_pass_jumpint, optional

Positive integer determining the linear interpolation step. If larger than 1, the LOESS is used every low_pass_jump points and values between the two are linearly interpolated. Higher values reduce estimation time.

See also

statsmodels.tsa.arima.model.ARIMA

ARIMA modeling.

statsmodels.tsa.ar_model.AutoReg

Autoregressive modeling supporting complex deterministics.

statsmodels.tsa.exponential_smoothing.ets.ETSModel

Additive and multiplicative exponential smoothing with trend.

statsmodels.tsa.statespace.exponential_smoothing.ExponentialSmoothing

Additive exponential smoothing with trend.

Notes

If \(\hat{S}_t\) is the seasonal component, then the deseasonalize series is constructed as

\[Y_t - \hat{S}_t\]

The trend component is not removed, and so the time series model should be capable of adequately fitting and forecasting the trend if present. The out-of-sample forecasts of the seasonal component are produced as

\[\hat{S}_{T + h} = \hat{S}_{T - k}\]

where \(k = m - h + m \lfloor (h-1)/m \rfloor\) tracks the period offset in the full cycle of 1, 2, …, m where m is the period length.

This class is mostly a convenience wrapper around STL and a user-specified model. The model is assumed to follow the standard statsmodels pattern:

• fit is used to estimate parameters and returns a results instance, results.

• results must exposes a method forecast(steps, **kwargs) that produces out-of-sample forecasts.

• results may also exposes a method get_prediction that produces both in- and out-of-sample predictions.

See the notebook Seasonal Decomposition for an overview.

Examples

>>> import numpy as np
>>> import pandas as pd
>>> from statsmodels.tsa.api import STLForecast
>>> from statsmodels.tsa.arima.model import ARIMA
>>> from statsmodels.datasets import macrodata
>>> ds = macrodata.load_pandas()
>>> data = np.log(ds.data.m1)
>>> base_date = f"{int(ds.data.year[0])}-{3*int(ds.data.quarter[0])+1}-1"
>>> data.index = pd.date_range(base_date, periods=data.shape[0], freq="QS")

Generate forecasts from an ARIMA

>>> stlf = STLForecast(data, ARIMA, model_kwargs={"order": (2, 1, 0)})
>>> res = stlf.fit()
>>> forecasts = res.forecast(12)

Generate forecasts from an Exponential Smoothing model with trend

>>> from statsmodels.tsa.statespace import exponential_smoothing
>>> ES = exponential_smoothing.ExponentialSmoothing
>>> config = {"trend": True}
>>> stlf = STLForecast(data, ES, model_kwargs=config)
>>> res = stlf.fit()
>>> forecasts = res.forecast(12)

Methods

fit(*[, inner_iter, outer_iter, fit_kwargs])

Estimate STL and forecasting model parameters.