HoltWinters

chronax.models.HoltWinters · inherits BaseForecaster

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

__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.

Parameters:

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.

Parameters:

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.

Parameters:

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.

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}').

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.

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}').