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 ⌊ (h - 1) / m ⌋$ 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.