BayesianETS

class pymc_extras.statespace.models.BayesianETS(order: tuple[str, str, str] | None = None, endog_names: str | Sequence[str] | None = None, trend: bool = True, damped_trend: bool = False, seasonal: bool = False, seasonal_periods: int | None = None, measurement_error: bool = False, use_transformed_parameterization: bool = False, dense_innovation_covariance: bool = False, stationary_initialization: bool = False, initialization_dampening: float = 0.8, filter_type: str = 'standard', verbose: bool = True, mode: str | Mode | None = None)

Exponential Smoothing State Space Model

This class can represent a subset of exponential smoothing state space models, specifically those with additive errors. Following .. [1], The general form of the model is:

\[\begin{split}\begin{align} y_t &= l_{t-1} + b_{t-1} + s_{t-m} + \epsilon_t \\ \epsilon_t &\sim N(0, \sigma) \end{align}\end{split}\]

where \(l_t\) is the level component, \(b_t\) is the trend component, and \(s_t\) is the seasonal component. These components can be included or excluded, leading to different model specifications. The following models are possible:

• ETS(A,N,N): Simple exponential smoothing

  \[\begin{split}\begin{align} y_t &= l_{t-1} + \epsilon_t \\ l_t &= l_{t-1} + \alpha \epsilon_t \end{align}\end{split}\]

Where \(\alpha \in [0, 1]\) is a mixing parameter between past observations and current innovations. These equations arise by starting from the “component form”:

\[\begin{split}\begin{align} \hat{y}_{t+1 | t} &= l_t \\ l_t &= \alpha y_t + (1 - \alpha) l_{t-1} \\ &= l_{t-1} + \alpha (y_t - l_{t-1}) &= l_{t-1} + \alpha \epsilon_t \end{align}\end{split}\]

Where $epsilon_t$ are the forecast errors, assumed to be IID mean zero and normally distributed. The role of \(\alpha\) is clearest in the second line. The level of the time series at each time is a mixture of \(\alpha\) percent of the incoming data, and \(1 - \alpha\) percent of the previous level. Recursive substitution reveals that the level is a weighted composite of all previous observations; thus the name “Exponential Smoothing”.

Additional supposed specifications include:

• ETS(A,A,N): Holt’s linear trend method

  \[\begin{split}\begin{align} y_t &= l_{t-1} + b_{t-1} + \epsilon_t \\ l_t &= l_{t-1} + b_{t-1} + \alpha \epsilon_t \\ b_t &= b_{t-1} + \alpha \beta^\star \epsilon_t \end{align}\end{split}\]

  [1] also consider an alternative parameterization with \(\beta = \alpha \beta^\star\).

• ETS(A,N,A): Additive seasonal method

  \[\begin{split}\begin{align} y_t &= l_{t-1} + s_{t-m} + \epsilon_t \\ l_t &= l_{t-1} + \alpha \epsilon_t \\ s_t &= s_{t-m} + (1 - \alpha)\gamma^\star \epsilon_t \end{align}\end{split}\]

  [1] also consider an alternative parameterization with \(\gamma = (1 - \alpha) \gamma^\star\).

• ETS(A,A,A): Additive Holt-Winters method

  \[\begin{split}\begin{align} y_t &= l_{t-1} + b_{t-1} + s_{t-m} + \epsilon_t \\ l_t &= l_{t-1} + \alpha \epsilon_t \\ b_t &= b_{t-1} + \alpha \beta^\star \epsilon_t \\ s_t &= s_{t-m} + (1 - \alpha) \gamma^\star \epsilon_t \end{align}\end{split}\]

  [1] also consider an alternative parameterization with \(\beta = \alpha \beta^star\) and \(\gamma = (1 - \alpha) \gamma^\star\).

• ETS(A, Ad, N): Dampened trend method

  \[\begin{split}\begin{align} y_t &= l_{t-1} + b_{t-1} + \epsilon_t \\ l_t &= l_{t-1} + \alpha \epsilon_t \\ b_t &= \phi b_{t-1} + \alpha \beta^\star \epsilon_t \end{align}\end{split}\]

  [1] also consider an alternative parameterization with \(\beta = \alpha \beta^\star\).

• ETS(A, Ad, A): Dampened trend with seasonal method

  \[\begin{split}\begin{align} y_t &= l_{t-1} + b_{t-1} + s_{t-m} + \epsilon_t \\ l_t &= l_{t-1} + \alpha \epsilon_t \\ b_t &= \phi b_{t-1} + \alpha \beta^\star \epsilon_t \\ s_t &= s_{t-m} + (1 - \alpha) \gamma^\star \epsilon_t \end{align}\end{split}\]

  [1] also consider an alternative parameterization with \(\beta = \alpha \beta^star\) and \(\gamma = (1 - \alpha) \gamma^\star\).

Parameters:

• order (tuple of string, Optional) – The exponential smoothing “order”. This is a tuple of three strings, each of which should be one of ‘A’, ‘Ad’, or ‘N’. If provided, the model will be initialized from the given order, and the trend, damped_trend, and seasonal arguments will be ignored.

• endog_names (str or Sequence of str) – Names associated with observed states. If a list, the length should be equal to the number of time series to be estimated.

• trend (bool) – Whether to include a trend component. Setting trend=True is equivalent to order[1] == 'A'.

• damped_trend (bool) – Whether to include a damping parameter on the trend component. Ignored if trend is False. Setting trend=True and damped_trend=True is equivalent to order[1] == ‘Ad’.

• seasonal (bool) – Whether to include a seasonal component. Setting seasonal=True is equivalent to order[2] = 'A'.

• seasonal_periods (int) – The number of periods in a complete seasonal cycle. Ignored if seasonal is False (or if order[2] == "N")

• measurement_error (bool) – Whether to include a measurement error term in the model. Default is False.

• use_transformed_parameterization (bool, default False) –

  If true, use the \(\alpha, \beta, \gamma\) parameterization, otherwise use the \(\alpha, \beta^\star, \gamma^\star\) parameterization. This will change the admissible region for the priors.

  • Under the non-transformed parameterization, all of \(\alpha, \beta^\star, \gamma^\star\) should be between 0 and 1.

  • Under the transformed parameterization, \(\alpha \in (0, 1)\), \(\beta \in (0, \alpha)\), and \(\gamma \in (0, 1 - \alpha)\)

  The param_info() method will change to reflect the suggested intervals based on the value of this argument.

• dense_innovation_covariance (bool, default False) – Whether to estimate a dense covariance for statespace innovations. In an ETS models, each observed variable has a single source of stochastic variation. If True, these innovations are allowed to be correlated. Ignored if k_endog == 1

• stationary_initialization (bool, default False) –

  If True, the Kalman Filter’s initial covariance matrix will be set to an approximate steady-state value. The approximation is formed by adding a small dampening factor to each state. Specifically, the level state for a (‘A’, ‘N’, ‘N’) model is written:

  \[\ell_t = \ell_{t-1} + \alpha * e_t\]

  That this system is not stationary can be understood in ARIMA terms: the level is a random walk; that is, \(rho = 1\). This can be remedied by pretending that we instead have a dampened system:

  \[\ell_t = \rho \ell_{t-1} + \alpha * e_t\]

  With \(\rho \approx 1\), the system is stationary, and we can solve for the steady-state covariance matrix. This is then used as the initial covariance matrix for the Kalman Filter. This is a heuristic method that helps avoid setting a prior on the initial covariance matrix.

• initialization_dampening (float, default 0.8) – Dampening factor to add to non-stationary model components. This is only used for initialization, it does not add dampening to the model. Ignored if stationary_initialization is False.

• filter_type (str, default "standard") – The type of Kalman Filter to use. Options are “standard”, “single”, “univariate”, “steady_state”, and “cholesky”. See the docs for kalman filters for more details.

• verbose (bool, default True) – If true, a message will be logged to the terminal explaining the variable names, dimensions, and supports.

• mode (str or Mode, optional) –

  Pytensor compile mode, used in auxiliary sampling methods such as sample_conditional_posterior and forecast. The mode does not effect calls to pm.sample.

  Regardless of whether a mode is specified, it can always be overwritten via the compile_kwargs argument to all sampling methods.

References

[1] (1,2,3,4,5)

Hyndman, Rob J., and George Athanasopoulos. Forecasting: principles and practice. OTexts, 2018.

__init__(order: tuple[str, str, str] | None = None, endog_names: str | Sequence[str] | None = None, trend: bool = True, damped_trend: bool = False, seasonal: bool = False, seasonal_periods: int | None = None, measurement_error: bool = False, use_transformed_parameterization: bool = False, dense_innovation_covariance: bool = False, stationary_initialization: bool = False, initialization_dampening: float = 0.8, filter_type: str = 'standard', verbose: bool = True, mode: str | Mode | None = None)

Methods

__init__([order, endog_names, trend, ...])
add_default_priors()	Add default priors to the active PyMC model context
build_statespace_graph(data[, ...])	Given a parameter vector theta, constructs the full computational graph describing the state space model and the associated log probability of the data.
default_coords()
forecast(idata[, start, periods, end, ...])	Generate forecasts of state space model trajectories into the future.
impulse_response_function(idata[, n_steps, ...])	Generate impulse response functions (IRF) from state space model dynamics.
make_and_register_data(name, shape[, dtype])	Helper function to create a pytensor symbolic variable and register it in the _name_to_data dictionary
make_and_register_variable(name[, shape, dtype])	Helper function to create a pytensor symbolic variable and register it in the _name_to_variable dictionary
make_symbolic_graph()	The purpose of the make_symbolic_graph function is to hide tedious parameter allocations from the user.
sample_conditional_posterior(idata[, ...])	Sample from the conditional posterior; that is, given parameter draws from the posterior distribution, compute Kalman filtered trajectories.
sample_conditional_prior(idata[, ...])	Sample from the conditional prior; that is, given parameter draws from the prior distribution, compute Kalman filtered trajectories.
sample_filter_outputs(idata[, ...])
sample_statespace_matrices(idata, matrix_names)	Draw samples of requested statespace matrices from provided idata
sample_unconditional_posterior(idata[, ...])	Draw unconditional sample trajectories according to state space dynamics, using random samples from the posterior distribution over model parameters.
sample_unconditional_prior(idata[, steps, ...])	Draw unconditional sample trajectories according to state space dynamics, using random samples from the prior distribution over model parameters.
set_coords()	Provide coordinates to the model.
set_data_info()	Provide data_info metadata to the model.
set_parameters()	Provides parameter metadata to the model.
set_shocks()	Provide shock metadata to the model.
set_states()	Provide state metadata to the model.
unpack_statespace()	Helper function to quickly obtain all statespace matrices in the standard order.

Attributes

coords	PyMC model coordinates
data_info	Information about Data variables that need to be declared in the PyMC model block.
data_names	Names of data variables expected by the model.
default_priors	Dictionary of parameter names and callable functions to construct default priors for the model
n_timesteps	Symbolic placeholder for the number of time steps in the data.
observed_states	A k_endog length list of strings, associated with the model's observed states
param_dims	Dictionary of named dimensions for each model parameter
param_info	Information about parameters needed to declare priors
param_names	Names of model parameters
shock_names	A k_posdef length list of strings, associated with the model's shock processes
state_names	A k_states length list of strings, associated with the model's hidden states