statsmodels.tsa.exponential_smoothing.ets.ETSModel

class statsmodels.tsa.exponential_smoothing.ets.ETSModel(endog, error='add', trend=None, damped_trend=False, seasonal=None, seasonal_periods=None, initialization_method='estimated', initial_level=None, initial_trend=None, initial_seasonal=None, bounds=None, dates=None, freq=None, missing='none')[source]

ETS models.

Parameters:
endogarray_like

The observed time-series process \(y\)

errorstr, optional

The error model. “add” (default) or “mul”.

trendstr or None, optional

The trend component model. “add”, “mul”, or None (default).

damped_trendbool, optional

Whether or not an included trend component is damped. Default is False.

seasonalstr, optional

The seasonality model. “add”, “mul”, or None (default).

seasonal_periodsint, optional

The number of periods in a complete seasonal cycle for seasonal (Holt-Winters) models. For example, 4 for quarterly data with an annual cycle or 7 for daily data with a weekly cycle. Required if seasonal is not None.

initialization_methodstr, optional

Method for initialization of the state space model. One of:

  • ‘estimated’ (default)

  • ‘heuristic’

  • ‘known’

If ‘known’ initialization is used, then initial_level must be passed, as well as initial_trend and initial_seasonal if applicable. ‘heuristic’ uses a heuristic based on the data to estimate initial level, trend, and seasonal state. ‘estimated’ uses the same heuristic as initial guesses, but then estimates the initial states as part of the fitting process. Default is ‘estimated’.

initial_levelfloat, optional

The initial level component. Only used if initialization is ‘known’.

initial_trendfloat, optional

The initial trend component. Only used if initialization is ‘known’.

initial_seasonalarray_like, optional

The initial seasonal component. An array of length seasonal_periods. Only used if initialization is ‘known’.

boundsdict or None, optional

A dictionary with parameter names as keys and the respective bounds intervals as values (lists/tuples/arrays). The available parameter names are, depending on the model and initialization method:

  • “smoothing_level”

  • “smoothing_trend”

  • “smoothing_seasonal”

  • “damping_trend”

  • “initial_level”

  • “initial_trend”

  • “initial_seasonal.0”, …, “initial_seasonal.<m-1>”

The default option is None, in which case the traditional (nonlinear) bounds as described in [1] are used.

Notes

The ETS models are a family of time series models. They can be seen as a generalization of simple exponential smoothing to time series that contain trends and seasonalities. Additionally, they have an underlying state space model.

An ETS model is specified by an error type (E; additive or multiplicative), a trend type (T; additive or multiplicative, both damped or undamped, or none), and a seasonality type (S; additive or multiplicative or none). The following gives a very short summary, a more thorough introduction can be found in [1].

Denote with \(\circ_b\) the trend operation (addition or multiplication), with \(\circ_d\) the operation linking trend and dampening factor \(\phi\) (multiplication if trend is additive, power if trend is multiplicative), and with \(\circ_s\) the seasonality operation (addition or multiplication). Furthermore, let \(\ominus\) be the respective inverse operation (subtraction or division).

With this, it is possible to formulate the ETS models as a forecast equation and 3 smoothing equations. The former is used to forecast observations, the latter are used to update the internal state.

\[\begin{split}\hat{y}_{t|t-1} &= (l_{t-1} \circ_b (b_{t-1}\circ_d \phi)) \circ_s s_{t-m}\\ l_{t} &= \alpha (y_{t} \ominus_s s_{t-m}) + (1 - \alpha) (l_{t-1} \circ_b (b_{t-1} \circ_d \phi))\\ b_{t} &= \beta/\alpha (l_{t} \ominus_b l_{t-1}) + (1 - \beta/\alpha) b_{t-1}\\ s_{t} &= \gamma (y_t \ominus_s (l_{t-1} \circ_b (b_{t-1}\circ_d\phi)) + (1 - \gamma) s_{t-m}\end{split}\]

The notation here follows [1]; \(l_t\) denotes the level at time \(t\), b_t the trend, and s_t the seasonal component. \(m\) is the number of seasonal periods, and \(\phi\) a trend damping factor. The parameters \(\alpha, \beta, \gamma\) are the smoothing parameters, which are called smoothing_level, smoothing_trend, and smoothing_seasonal, respectively.

Note that the formulation above as forecast and smoothing equation does not distinguish different error models – it is the same for additive and multiplicative errors. But the different error models lead to different likelihood models, and therefore will lead to different fit results.

The error models specify how the true values \(y_t\) are updated. In the additive error model,

\[y_t = \hat{y}_{t|t-1} + e_t,\]

in the multiplicative error model,

\[y_t = \hat{y}_{t|t-1}\cdot (1 + e_t).\]

Using these error models, it is possible to formulate state space equations for the ETS models:

\[\begin{split}y_t &= Y_t + \eta \cdot e_t\\ l_t &= L_t + \alpha \cdot (M_e \cdot L_t + \kappa_l) \cdot e_t\\ b_t &= B_t + \beta \cdot (M_e \cdot B_t + \kappa_b) \cdot e_t\\ s_t &= S_t + \gamma \cdot (M_e \cdot S_t+\kappa_s)\cdot e_t\\\end{split}\]

with

\[\begin{split}B_t &= b_{t-1} \circ_d \phi\\ L_t &= l_{t-1} \circ_b B_t\\ S_t &= s_{t-m}\\ Y_t &= L_t \circ_s S_t,\end{split}\]

and

\[\begin{split}\eta &= \begin{cases} Y_t\quad\text{if error is multiplicative}\\ 1\quad\text{else} \end{cases}\\ M_e &= \begin{cases} 1\quad\text{if error is multiplicative}\\ 0\quad\text{else} \end{cases}\\\end{split}\]

and, when using the additive error model,

\[\begin{split}\kappa_l &= \begin{cases} \frac{1}{S_t}\quad \text{if seasonality is multiplicative}\\ 1\quad\text{else} \end{cases}\\ \kappa_b &= \begin{cases} \frac{\kappa_l}{l_{t-1}}\quad \text{if trend is multiplicative}\\ \kappa_l\quad\text{else} \end{cases}\\ \kappa_s &= \begin{cases} \frac{1}{L_t}\quad\text{if seasonality is multiplicative}\\ 1\quad\text{else} \end{cases}\end{split}\]

When using the multiplicative error model

\[\begin{split}\kappa_l &= \begin{cases} 0\quad \text{if seasonality is multiplicative}\\ S_t\quad\text{else} \end{cases}\\ \kappa_b &= \begin{cases} \frac{\kappa_l}{l_{t-1}}\quad \text{if trend is multiplicative}\\ \kappa_l + l_{t-1}\quad\text{else} \end{cases}\\ \kappa_s &= \begin{cases} 0\quad\text{if seasonality is multiplicative}\\ L_t\quad\text{else} \end{cases}\end{split}\]

When fitting an ETS model, the parameters \(\alpha, \beta\), gamma, phi` and the initial states l_{-1}, b_{-1}, s_{-1}, ldots, s_{-m} are selected as maximizers of log likelihood.

References

[1] (1,2,3)

Hyndman, R.J., & Athanasopoulos, G. (2019) Forecasting: principles and practice, 3rd edition, OTexts: Melbourne, Australia. OTexts.com/fpp3. Accessed on April 19th 2020.

Attributes:
endog_names

Names of endogenous variables.

exog_names

The names of the exogenous variables.

initial_state_names
k_endog
k_params
nobs_effective
param_names

(list of str) List of human readable parameter names (for parameters

short_name
start_params

(array) Starting parameters for maximum likelihood estimation.

state_names

Methods

clone(endog[, exog])

fit([start_params, maxiter, full_output, ...])

Fit an ETS model by maximizing log-likelihood.

fit_constrained(constraints[, start_params])

Fit the model with some parameters subject to equality constraints.

fix_params(params)

Fix parameters to specific values (context manager)

from_formula(formula, data[, subset, drop_cols])

Not implemented for state space models

hessian(params[, approx_centered, ...])

Hessian matrix of the likelihood function, evaluated at the given parameters

information(params)

Fisher information matrix of model.

initialize()

Initialize (possibly re-initialize) a Model instance.

loglike(params, **kwargs)

Log-likelihood of model.

predict(params[, exog])

After a model has been fit predict returns the fitted values.

prepare_data(data)

Prepare data for use in the state space representation

score(params[, approx_centered, ...])

Score vector of model.

set_bounds(bounds)

Set bounds for parameter estimation.

set_initialization_method(initialization_method)

Sets a new initialization method for the state space model.

smooth(params[, return_raw])

Exponential smoothing with given parameters

update(*args, **kwargs)

use_internal_loglike()

Properties

endog_names

Names of endogenous variables.

exog_names

The names of the exogenous variables.

initial_state_names

k_endog

k_params

nobs_effective

param_names

(list of str) List of human readable parameter names (for parameters actually included in the model).

short_name

start_params

(array) Starting parameters for maximum likelihood estimation.

state_names