smooth.ES

class smooth.ES(model='ZXZ', lags=None, persistence=None, phi=None, initial='backcasting', initial_season=None, ic='AICc', loss='likelihood', h=None, holdout=False, bounds='usual', smoother='default', verbose=0, regressors='use', initial_X=None, **kwargs)

Exponential Smoothing in Single Source of Error (SSOE) state space model.

This class is a wrapper around ADAM that provides a simplified interface for pure ETS (Error, Trend, Seasonal) models without ARIMA components. It uses normal distribution for errors and conventional ETS formulation.

The model is specified in state-space form as:

\[ \begin{align}\begin{aligned}y_t &= o_t(w(v_{t-l}) + h(x_t, a_{t-1}) + r(v_{t-l})\epsilon_t)\\v_t &= f(v_{t-l}) + g(v_{t-l})\epsilon_t\end{aligned}\end{align} \]

where:

• \(y_t\): Observed value at time t

• \(o_t\): Occurrence indicator (Bernoulli variable for intermittent data)

• \(v_t\): State vector (level, trend, seasonal components)

• \(l\): Vector of lags

• \(w(\cdot)\): Measurement function

• \(r(\cdot)\): Error function (additive or multiplicative)

• \(f(\cdot)\): Transition function

• \(g(\cdot)\): Persistence function

• \(\epsilon_t\): Error term (normal distribution)

Parameters:

• model (Union[str, List[str]]) –

  The type of ETS model. The first letter stands for the type of error (“A” or “M”), the second for trend (“N”, “A”, “Ad”, “M” or “Md”), and the third for seasonality (“N”, “A” or “M”).

  Examples: “ANN”, “AAN”, “AAdN”, “AAA”, “AAdA”, “MAdM”

  Special codes: - “ZZZ”: Automatic selection using information criteria - “XXX”: Select only additive components - “YYY”: Select only multiplicative components - “ZXZ”: Auto-select error and seasonal, additive trend only (default) - “CCC”: Combination of all models using AIC weights

  Can also be a list of model names for custom model pool.

• lags (Optional[List[int]]) – Seasonal period(s). Can be a single integer or a list of integers. E.g., lags=12 is equivalent to lags=[12]. For monthly data with annual seasonality: lags=12 or lags=[1, 12]. If None, defaults to [1] (no seasonality).

• persistence (Optional[Dict[str, float]]) – Fixed persistence (smoothing) parameters. If None, estimated. Keys: “alpha” (level), “beta” (trend), “gamma” (seasonal).

• phi (Optional[float]) – Damping parameter for damped trend models. If None, estimated when applicable.

• initial (Union[str, Dict[str, Any], None]) – Method for initializing states or dictionary of fixed initial values. String options: “backcasting”, “optimal”, “complete”, “two-stage”

• initial_season (Optional[NDArray]) – Initial values for seasonal components. If None, estimated. Length should be (seasonal_period - 1) for each seasonal component.

• ic (Literal['AIC', 'AICc', 'BIC', 'BICc']) – Information criterion for model selection.

• loss (Literal['likelihood', 'GPL', 'MSE', 'MAE', 'HAM', 'MSEh', 'MAEh', 'HAMh', 'MSCE', 'MACE', 'CHAM', 'TMSE', 'TMAE', 'THAM', 'GTMSE', 'GTAME', 'GTHAM', 'LASSO', 'RIDGE']) – Loss function for parameter estimation.

• h (Optional[int]) – Forecast horizon. Can also be set in predict().

• holdout (bool) – Whether to use holdout sample for validation.

• bounds (Literal['usual', 'admissible', 'none']) – Parameter bounds type: - “usual”: Standard smoothing parameter constraints - “admissible”: Stability constraints - “none”: No constraints

• verbose (int) – Verbosity level. 0 = silent.

• regressors (Literal['use', 'select']) – How to handle external regressors.

• initial_X (Optional[NDArray]) – Initial values for regressor coefficients.

• **kwargs – Additional arguments passed to ADAM.

See also

ADAM

Parent class with full attribute documentation including persistence_vector, states, fitted, residuals, phi_, coef, and all other properties.

Examples

Simple exponential smoothing:

>>> from smooth.adam_general.core.es import ES
>>> import numpy as np
>>> y = np.array([112, 118, 132, 129, 121, 135, 148, 148, 136, 119, 104, 118])
>>> model = ES(model="ANN")
>>> model.fit(y)
>>> forecasts = model.predict(h=6)

Holt-Winters with automatic model selection:

>>> model = ES(model="ZZZ", lags=[12])
>>> model.fit(y)
>>> print(f"Selected model: {model.model_type}")

Damped trend model:

>>> model = ES(model="AAdN")
>>> model.fit(y)
>>> print(f"Damping parameter: {model.phi_:.3f}")

With external regressors:

>>> X = np.random.randn(len(y), 2)
>>> model = ES(model="AAN", regressors="use")
>>> model.fit(y, X=X)

References

• Svetunkov, I. (2023). Forecasting and Analytics with the Augmented Dynamic Adaptive Model. https://openforecast.org/adam/

• Hyndman, R.J., et al. (2008). “Forecasting with Exponential Smoothing”

See also

ADAM

Full ADAM model with ETS and ARIMA components

Methods

coefbootstrap([nsim, size, replace, prob, ...])	Bootstrap the coefficient sampling distribution by refitting subsamples.
confint([parm, level, type, bootstrap, ...])	Confidence intervals for the estimated parameters.
fit(y[, X])	Fit the ADAM model to time series data.
multicov([type, h, nsim])	Covariance matrix of multi-step-ahead forecast errors.
outlierdummy([level, type])	Detect outliers and return a matrix of indicator dummy variables.
plot([which, level, legend, lowess])	Diagnostic plots for the fitted ADAM model (R: plot.adam).
point_lik([log])	Per-observation log-likelihood of the fitted model.
predict(h[, X, interval, level, side, ...])	Generate forecasts using the fitted ADAM model.
predict_intervals(h[, X, levels, side, nsim])	Generate prediction intervals using the fitted ADAM model.
reapply([nsim, type, bootstrap, heuristics, ...])	Re-run the model on the in-sample data for nsim parameter draws.
reforecast([h, X, occurrence, interval, ...])	Produce h-step-ahead forecasts via Monte-Carlo reforecasting.
rmultistep([h])	Return the (T-h) × h matrix of rolling in-sample multistep forecast errors.
rstandard()	Return standardised residuals.
rstudent()	Return studentised (leave-one-out) residuals.
select_best_model()	Select the best model based on information criteria and update model parameters.
simulate([nsim, seed, obs, randomizer])	Re-simulate obs observations from the fitted model.
summary([level, digits, type])	Generate a coefficient-table summary of the fitted model.
vcov([type, bootstrap, heuristics, step_size])	Variance-covariance matrix of the estimated parameters.

Attributes

actuals	Return original in-sample data.
aic	Return Akaike Information Criterion.
aicc	Return corrected Akaike Information Criterion.
b_value	$B).
bic	Return Bayesian Information Criterion.
bicc	Return corrected Bayesian Information Criterion.
coef	Return estimated coefficients (parameter vector B).
coef_names	Parameter names aligned with coef (the B vector).
constant_value	$constant).
data	$data).
distribution_	$distribution).
error_type	'A' (additive) or 'M' (multiplicative).
fisher_information_	Observed Fisher Information matrix at the estimated parameters.
fitted	Return in-sample fitted values.
holdout_data	$holdout).
ic_weights	$ICw).
initial_type	$initialType).
initial_value	$initial).
is_combined	Return True if model is a combination of multiple models.
lags_used	Return the vector of lags used in the model.
loglik	Return log-likelihood of the fitted model.
loss_	$loss).
loss_value	$lossValue).
measurement	$measurement).
model_name	modelName()).
model_type	Return ETS model type code (e.g., 'AAN', 'AAA', 'MAdM').
models	$models).
n_param	$nParam).
nobs	Return number of observations used for fitting.
nparam	Return number of estimated parameters.
om_model	Fitted occurrence model (OM / OMG / AutoOM), or None.
orders	Return ARIMA orders as dict with 'ar', 'i', 'ma' keys.
persistence_vector	$persistence).
phi_	$phi).
profile	$profile).
residuals	Return model residuals (errors from fitting).
scale	Internal optimisation scale of the error distribution (R: adam_obj$scale).
sigma	sigma(adam_obj)).
states	$states).
time_elapsed	Time taken to fit the model in seconds.
transition	$transition).