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.

Holt

chronax.models.Holt · inherits BaseForecaster

Holt's linear exponential smoothing method.

The model fits level and trend smoothing parameters (alpha, beta) using maximum likelihood optimization via gradient descent.

Attributes: * uses_exog: bool (False) * alias: str (Custom name for the model) * conformal_params: ConformalIntervals | None (Parameters for conformal prediction intervals) * model_: dict (Fitted model parameters, available after fit(). Includes fitted, level, trend, alpha, beta, sigma, residuals, y_train.)

__init__(self, season_length=1, error_type='A', damped=None, phi=None, alias='Holt', conformal_params=None, allow_extended_iterations=False, iteration_scaling='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'. * ValueError: If phi is not a float when provided. * ValueError: If phi is outside the valid range [0.8, 0.98]. * ValueError: If conformal_params is not a ConformalIntervals instance. * ValueError: If iteration_scaling is not 'quadratic' or 'cubic'.

fit(self, y, X=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.

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 model instance; sets self.model_). Raises: * ValueError: If y has fewer than 2 observations.

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

Predict with fitted Holt model.

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' for point predictions and 'lo-{level}' and 'hi-{level}' for probabilistic predictions.) Return Keys: * mean: jnp.ndarray * lo-{level}: jnp.ndarray (if level is provided) * hi-{level}: jnp.ndarray (if level is provided) 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=None) -> dict

Access fitted Holt model insample predictions.

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

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

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

Memory efficient Holt predictions.

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

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' for point predictions, 'fitted' for insample predictions (if fitted=True), and 'lo-{level}' and 'hi-{level}' for probabilistic predictions.) Return Keys: * mean: jnp.ndarray * fitted: jnp.ndarray (if fitted=True) * lo-{level}: jnp.ndarray (if level is provided) * hi-{level}: jnp.ndarray (if level is provided) * fitted-lo-{level}: jnp.ndarray (if fitted=True and level is provided) * fitted-hi-{level}: jnp.ndarray (if fitted=True and level is provided) 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, h, X=None, X_future=None, level=None, fitted=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.

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' for point predictions, 'fitted' for insample predictions (if fitted=True), and 'lo-{level}' and 'hi-{level}' for probabilistic predictions.) Return Keys: * mean: jnp.ndarray * fitted: jnp.ndarray (if fitted=True) * lo-{level}: jnp.ndarray (if level is provided) * hi-{level}: jnp.ndarray (if level is provided) * fitted-lo-{level}: jnp.ndarray (if fitted=True and level is provided) * fitted-hi-{level}: jnp.ndarray (if fitted=True and level is provided) 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].