statsmodels.tsa.statespace.exponential_smoothing.ExponentialSmoothing

class statsmodels.tsa.statespace.exponential_smoothing.ExponentialSmoothing(endog, trend=False, damped_trend=False, seasonal=None, initialization_method='estimated', initial_level=None, initial_trend=None, initial_seasonal=None, bounds=None, concentrate_scale=True, dates=None, freq=None, missing='none')[source]

Linear exponential smoothing models

Parameters:
endogarray_like

The observed time-series process \(y\)

trendbool, optional

Whether or not to include a trend component. Default is False.

damped_trendbool, optional

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

seasonalint, 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. Default is no seasonal effects.

initialization_methodstr, optional

Method for initialize the recursions. One of:

  • ‘estimated’

  • ‘concentrated’

  • ‘heuristic’

  • ‘known’

If ‘known’ initialization is used, then initial_level must be passed, as well as initial_slope and initial_seasonal if applicable. 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 or length seasonal - 1 (in which case the last initial value is computed to make the average effect zero). Only used if initialization is ‘known’.

boundsiterable[tuple], optional

An iterable containing bounds for the parameters. Must contain four elements, where each element is a tuple of the form (lower, upper). Default is (0.0001, 0.9999) for the level, trend, and seasonal smoothing parameters and (0.8, 0.98) for the trend damping parameter.

concentrate_scalebool, optional

Whether or not to concentrate the scale (variance of the error term) out of the likelihood.

Notes

Overview

The parameters and states of this model are estimated by setting up the exponential smoothing equations as a special case of a linear Gaussian state space model and applying the Kalman filter. As such, it has slightly worse performance than the dedicated exponential smoothing model, statsmodels.tsa.holtwinters.ExponentialSmoothing, and it does not support multiplicative (nonlinear) exponential smoothing models.

However, as a subclass of the state space models, this model class shares a consistent set of functionality with those models, which can make it easier to work with. In addition, it supports computing confidence intervals for forecasts and it supports concentrating the initial state out of the likelihood function.

Model timing

Typical exponential smoothing results correspond to the “filtered” output from state space models, because they incorporate both the transition to the new time point (adding the trend to the level and advancing the season) and updating to incorporate information from the observed datapoint. By contrast, the “predicted” output from state space models only incorporates the transition.

One consequence is that the “initial state” corresponds to the “filtered” state at time t=0, but this is different from the usual state space initialization used in Statsmodels, which initializes the model with the “predicted” state at time t=1. This is important to keep in mind if setting the initial state directly (via initialization_method=’known’).

Seasonality

In seasonal models, it is important to note that seasonals are included in the state vector of this model in the order: [seasonal, seasonal.L1, seasonal.L2, seasonal.L3, …]. At time t, the ‘seasonal’ state holds the seasonal factor operative at time t, while the ‘seasonal.L’ state holds the seasonal factor that would have been operative at time t-1.

Suppose that the seasonal order is n_seasons = 4. Then, because the initial state corresponds to time t=0 and the time t=1 is in the same season as time t=-3, the initial seasonal factor for time t=1 comes from the lag “L3” initial seasonal factor (i.e. at time t=1 this will be both the “L4” seasonal factor as well as the “L0”, or current, seasonal factor).

When the initial state is estimated (initialization_method=’estimated’), there are only n_seasons - 1 parameters, because the seasonal factors are normalized to sum to one. The three parameters that are estimated correspond to the lags “L0”, “L1”, and “L2” seasonal factors as of time t=0 (alternatively, the lags “L1”, “L2”, and “L3” as of time t=1).

When the initial state is given (initialization_method=’known’), the initial seasonal factors for time t=0 must be given by the argument initial_seasonal. This can either be a length n_seasons - 1 array – in which case it should contain the lags “L0” - “L2” (in that order) seasonal factors as of time t=0 – or a length n_seasons array, in which case it should contain the “L0” - “L3” (in that order) seasonal factors as of time t=0.

Note that in the state vector and parameters, the “L0” seasonal is called “seasonal” or “initial_seasonal”, while the i>0 lag is called “seasonal.L{i}”.

References

[1] Hyndman, Rob, Anne B. Koehler, J. Keith Ord, and Ralph D. Snyder.

Forecasting with exponential smoothing: the state space approach. Springer Science & Business Media, 2008.

Attributes:
endog_names

Names of endogenous variables.

exog_names

The names of the exogenous variables.

initial_variance
initialization
k_params
loglikelihood_burn
param_names

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

start_params

(array) Starting parameters for maximum likelihood estimation.

state_names

(list of str) List of human readable names for unobserved states.

tolerance

Methods

clone(endog[, exog])

Clone state space model with new data and optionally new specification

filter(params[, cov_type, cov_kwds, ...])

Kalman filtering

fit([start_params, transformed, ...])

Fits the model by maximum likelihood via Kalman filter.

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])

Not implemented for state space models

handle_params(params[, transformed, ...])

Ensure model parameters satisfy shape and other requirements

hessian(params, *args, **kwargs)

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

impulse_responses(params[, steps, impulse, ...])

Impulse response function

information(params)

Fisher information matrix of model.

initialize()

Initialize (possibly re-initialize) a Model instance.

initialize_approximate_diffuse([variance])

Initialize approximate diffuse

initialize_known(initial_state, ...)

Initialize known

initialize_statespace(**kwargs)

Initialize the state space representation

initialize_stationary()

Initialize stationary

loglike(params, *args, **kwargs)

Loglikelihood evaluation

loglikeobs(params[, transformed, ...])

Loglikelihood evaluation

observed_information_matrix(params[, ...])

Observed information matrix

opg_information_matrix(params[, ...])

Outer product of gradients information matrix

predict(params[, exog])

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

prepare_data()

Prepare data for use in the state space representation

score(params, *args, **kwargs)

Compute the score function at params.

score_obs(params[, method, transformed, ...])

Compute the score per observation, evaluated at params

set_conserve_memory([conserve_memory])

Set the memory conservation method

set_filter_method([filter_method])

Set the filtering method

set_inversion_method([inversion_method])

Set the inversion method

set_smoother_output([smoother_output])

Set the smoother output

set_stability_method([stability_method])

Set the numerical stability method

simulate(params, nsimulations[, ...])

Simulate a new time series following the state space model

simulation_smoother([simulation_output])

Retrieve a simulation smoother for the state space model.

smooth(params[, cov_type, cov_kwds, ...])

Kalman smoothing

transform_jacobian(unconstrained[, ...])

Jacobian matrix for the parameter transformation function

transform_params(unconstrained)

Transform unconstrained parameters used by the optimizer to constrained parameters used in likelihood evaluation

untransform_params(constrained)

Transform constrained parameters used in likelihood evaluation to unconstrained parameters used by the optimizer

update(params[, transformed, ...])

Update the parameters of the model

Properties

endog_names

Names of endogenous variables.

exog_names

The names of the exogenous variables.

initial_variance

initialization

k_params

loglikelihood_burn

param_names

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

start_params

(array) Starting parameters for maximum likelihood estimation.

state_names

(list of str) List of human readable names for unobserved states.

tolerance