Holt-Winters' Exponential Smoothing — JAX-accelerated implementation.

Implements triple exponential smoothing with additive/multiplicative error and seasonality variants, damped trend, and two-phase ADAM + L-BFGS optimization.

HoltWinters

chronax.models.HoltWinters · inherits BaseForecaster

Holt-Winters' seasonal exponential smoothing.

This model implements triple exponential smoothing (level, trend, seasonality) optimized using a two-phase approach (ADAM warm-up followed by L-BFGS refinement). It supports additive ('A') and multiplicative ('M') error and seasonality types, and optional damped trend.

Attributes: * season_length (int): Number of observations per unit of time (e.g., 12 for monthly). * error_type (str): Type of error: 'A' (additive) or 'M' (multiplicative). * season_type (str): Type of seasonality: 'A' (additive) or 'M' (multiplicative). * damped (bool): Whether a damped trend component is used. * phi (float | None): Damping parameter (0.8-0.98), used only if damped=True. * alias (str): Custom name for the model. * conformal_params (ConformalIntervals | None): Parameters for conformal prediction intervals. * model_ (dict): Fitted model parameters, available after calling fit(). Keys include: fitted (in-sample fitted values), level (final level state), trend (final trend state), seasonal (final seasonal states), alpha, beta, gamma (estimated smoothing parameters), sigma (residual standard error), residuals, and y_train (original training data).

__init__(self, season_length=12, error_type='A', season_type='A', damped=None, phi=None, alias='HoltWinters', conformal_params=None)

Initialize with error, season, and damping parameters.

Parameter	Type	Default	Description
season_length	int	12	Number of observations per unit of time. Must be >= 2.
error_type	str	'A'	Error type: 'A' (additive) or 'M' (multiplicative).
season_type	str	'A'	Seasonality type: 'A' (additive) or 'M' (multiplicative).
damped	bool \| None	None	Whether to use damped trend. None treated as False.
phi	float \| None	None	Damping parameter in [0.8, 0.98]. Only used if damped=True.
alias	str	"HoltWinters"	Custom name for the model.
conformal_params	ConformalIntervals \| None	None	Parameters for conformal prediction intervals.

fit(self, y, X=None) -> Self

Fit the Holt-Winters model.

Parameter	Type	Default	Description
y	jnp.ndarray	-	Clean time series of shape (n,).
X	jnp.ndarray \| None	None	Optional exogenous of shape (n, n_x).

Returns: Self (Fitted model instance; sets self.model_).

predict(self, h, X=None, level=None) -> dict

Predict with fitted Holt-Winters.

Parameter	Type	Default	Description
h	int	-	Forecast horizon.
X	jnp.ndarray \| None	None	Optional exogenous of shape (h, n_x).
level	list[int] \| None	None	Confidence levels (0-100) for prediction intervals.

Returns: dict (Keys: 'mean' and optionally 'lo-{lv}', 'hi-{lv}').

predict_in_sample(self, level=None) -> dict

Access fitted Holt-Winters in-sample predictions.

Parameter	Type	Default	Description
level	list[int] \| None	None	Confidence levels (0-100) for prediction intervals.

Returns: dict (Keys: 'fitted' and optionally 'fitted-lo-{lv}', 'fitted-hi-{lv}').

forecast(self, y, h, X=None, X_future=None, level=None, fitted=False) -> dict

Memory-efficient Holt-Winters predictions. Fits and forecasts without storing model state.

Parameter	Type	Default	Description
y	jnp.ndarray	-	Clean time series of shape (n,).
h	int	-	Forecast horizon.
X	jnp.ndarray \| None	None	Optional exogenous of shape (n, n_x).
X_future	jnp.ndarray \| None	None	Optional future exogenous of shape (h, n_x).
level	list[int] \| None	None	Confidence levels (0-100) for prediction intervals.
fitted	bool	False	Whether to return in-sample predictions.

Returns: dict (Keys: 'mean', and optionally 'fitted', 'lo-{lv}', 'hi-{lv}').

forward(self, y, h, X=None, X_future=None, level=None, fitted=False) -> dict

Apply fitted Holt-Winters model to a new time series. Uses the model structure from the original fit but re-estimates parameters.

Parameter	Type	Default	Description
y	jnp.ndarray	-	Clean time series of shape (n,).
h	int	-	Forecast horizon.
X	jnp.ndarray \| None	None	Optional exogenous of shape (n, n_x).
X_future	jnp.ndarray \| None	None	Optional future exogenous of shape (h, n_x).
level	list[int] \| None	None	Confidence levels (0-100) for prediction intervals.
fitted	bool	False	Whether to return in-sample predictions.

Returns: dict (Keys: 'mean', and optionally 'fitted', 'lo-{lv}', 'hi-{lv}').