Holt

chronax.models.holt.Holt · inherits BaseForecaster

Holt's Linear Exponential Smoothing Model. This module implements Holt's linear trend method (double exponential smoothing) with full JAX acceleration and compatibility with statsforecast's API.

Attributes: * uses_exog: bool (False) * alias: str * conformal_params: ConformalIntervals | None * model_: dict (Fitted model parameters, available after fit())

__init__(self, season_length: int = 1, error_type: str = 'A', damped: bool | None = None, phi: float | None = None, alias: str = "Holt", conformal_params: ConformalIntervals | None = None, allow_extended_iterations: bool = False, iteration_scaling: str = "quadratic")

Holt's linear exponential smoothing method.

Parameter	Type	Default	Description
season_length	int	1	Number of observations per unit of time. (Not used in current implementation but kept for API consistency.)
error_type	str	'A'	Type of error: 'A' (additive) or 'M' (multiplicative). Must be either 'A' or 'M'.
damped	bool \| None	None	Whether to use damped trend. If None, treated as False (non-damped).
phi	float \| None	None	Damping parameter, must be in [0.8, 0.98]. Only used if damped=True. If damped=True and phi=None, defaults to 0.9.
alias	str	"Holt"	Custom name for the model.
conformal_params	ConformalIntervals \| None	None	Parameters for conformal prediction intervals. If None, uses native analytical prediction intervals.
allow_extended_iterations	bool	False	Whether to allow extended iteration counts (up to 400) for difficult series. Default max is 200.
iteration_scaling	str	"quadratic"	Scaling method for adaptive iterations. "quadratic" (default) gives moderate scaling, "cubic" gives more aggressive scaling for complex series.

Raises: * ValueError: If error_type is not 'A' or 'M'. If phi is not a float when provided. If phi is outside the valid range [0.8, 0.98]. If conformal_params is not a ConformalIntervals instance. If iteration_scaling is not 'quadratic' or 'cubic'.

fit(self, y: jnp.ndarray, X: jnp.ndarray | None = None) -> Self

Fit the Holt model to training data.

This method estimates the smoothing parameters (alpha, beta) and computes the level and trend states by maximizing the log-likelihood using gradient descent optimization with JAX.

Parameters:

Parameter	Type	Default	Description
y	jnp.ndarray	-	Training time series data of shape (n,). Must have at least 2 observations.
X	jnp.ndarray \| None	None	Exogenous variables (not currently used, included for API consistency).

Returns: Self (the fitted forecaster; sets self.model_). Raises: * ValueError: If y has fewer than 2 observations.

predict(self, h: int, X: jnp.ndarray | None = None, level: list[int] | None = None) -> dict

Predict with fitted Holt model.

Parameters:

Parameter	Type	Default	Description
h	int	-	Forecast horizon (must be positive).
X	jnp.ndarray \| None	None	Exogenous variables (not used, included for API consistency).
level	list[int] \| None	None	Confidence levels (0-100) for prediction intervals.

Returns: dict (Dictionary with entries {"mean": jnp.ndarray} for point predictions, and optionally {"lo-{level}": jnp.ndarray, "hi-{level}": jnp.ndarray} for probabilistic predictions.) Raises: * ValueError: If model is not fitted, if h is not positive, or if level values are outside [0, 100].

predict_in_sample(self, level: list[int] | None = None) -> dict

Access fitted Holt model insample predictions.

Parameters:

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

Returns: dict (Dictionary with entries {"fitted": jnp.ndarray} for point predictions, and optionally {"fitted-lo-{level}": jnp.ndarray, "fitted-hi-{level}": jnp.ndarray} for probabilistic predictions.) Raises: * ValueError: If model is not fitted or if level values are outside [0, 100].

forecast(self, y: jnp.ndarray, h: int, X: jnp.ndarray | None = None, X_future: jnp.ndarray | None = None, level: list[int] | None = None, fitted: bool = False) -> dict

Memory efficient Holt predictions.

This method avoids memory burden from object storage. It is analogous to fit_predict without storing information.

Parameters:

Parameter	Type	Default	Description
y	jnp.ndarray	-	Clean time series of shape (n,). Must have at least 2 observations.
h	int	-	Forecast horizon (must be positive).
X	jnp.ndarray \| None	None	Insample exogenous variables (not used, included for API consistency).
X_future	jnp.ndarray \| None	None	Future exogenous variables (not used, included for API consistency).
level	list[int] \| None	None	Confidence levels (0-100) for prediction intervals.
fitted	bool	False	Whether to return insample predictions.

Returns: dict (Dictionary with entries {"mean": jnp.ndarray} for point predictions, optionally {"fitted": jnp.ndarray} for insample predictions (if fitted=True), and interval keys {"lo-{level}": jnp.ndarray, "hi-{level}": jnp.ndarray}.) Raises: * ValueError: If y has fewer than 2 observations, if h is not positive, or if level values are outside [0, 100].

forward(self, y: jnp.ndarray, h: int, X: jnp.ndarray | None = None, X_future: jnp.ndarray | None = None, level: list[int] | None = None, fitted: bool = False) -> dict

Apply fitted Holt model to a new time series.

This method uses the model structure (error_type, damped, phi) from the original fit, but re-estimates parameters on the new data.

Parameters:

Parameter	Type	Default	Description
y	jnp.ndarray	-	Clean time series of shape (n,). Must have at least 2 observations.
h	int	-	Forecast horizon (must be positive).
X	jnp.ndarray \| None	None	Insample exogenous variables (not used, included for API consistency).
X_future	jnp.ndarray \| None	None	Future exogenous variables (not used, included for API consistency).
level	list[int] \| None	None	Confidence levels (0-100) for prediction intervals.
fitted	bool	False	Whether to return insample predictions.

Returns: dict (Dictionary with entries {"mean": jnp.ndarray} for point predictions, optionally {"fitted": jnp.ndarray} for insample predictions (if fitted=True), and interval keys {"lo-{level}": jnp.ndarray, "hi-{level}": jnp.ndarray}.) Raises: * ValueError: If model is not fitted, if y has fewer than 2 observations, if h is not positive, or if level values are outside [0, 100].