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.
- model
Model
The model used to forecast endog after the seasonality has been removed using STL
- model_kwargs
Dict
[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.
- seasonal
int
,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_deg
int
,optional
Degree of seasonal LOESS. 0 (constant) or 1 (constant and trend).
- trend_deg
int
,optional
Degree of trend LOESS. 0 (constant) or 1 (constant and trend).
- low_pass_deg
int
,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_jump
int
,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_jump
int
,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_jump
int
,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.
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 methodforecast(steps, **kwargs)
that produces out-of-sample forecasts.results
may also exposes a methodget_prediction
that produces both in- and out-of-sample predictions.
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.