ETS

chronax.models.ets_model.ETS · inherits BaseForecaster

Fixed-specification Exponential Smoothing (ETS) forecaster. ETS decomposes a time series into level, trend, and seasonal components whose states are updated at each time step via smoothing parameters (α, β, γ, ϕ). The three-character model string specifies (Error, Trend, Season):

Character	Error	Trend	Season
A	Additive	Additive	Additive
M	Multiplicative	Multiplicative	Multiplicative
N	—	No trend	No seasonality

For example, "AAN" = Additive error + Additive trend + No seasonality.

Attributes:

• alias: str = "ETS"
• conformal_params: ConformalIntervals or None
• model_: dict Internal state dictionary produced by ets_f(…) after :meth:fit. Contains fitted parameters, AICc, fitted values, residuals, etc.

__init__(self, season_length=1, model='ANN', damped=None, phi=None, max_iter=None, optax_lr=0.01, optax_clip=1.0, alias='ETS', prediction_intervals=None)

Initialize a fixed-spec ETS estimator.

Parameter	Type	Default	Description
season_length	int	1	Seasonal period (e.g. 12 for monthly, 4 for quarterly). Use 1 for non-seasonal models.
model	str	"ANN"	Fixed ETS specification string. Common choices: "ANN" — simple exponential smoothing, "AAN" — Holt's linear trend, "AAA" — additive trend + additive seasonality
damped	Optional[bool]	None	Whether to apply trend damping. None is treated as False.
phi	Optional[float]	None	Damping coefficient. Must be in [0.8, 0.98] when provided.
max_iter	Optional[int]	None	Number of optax gradient-descent iterations. None lets the engine choose a sensible default based on data length and model complexity.
optax_lr	float	1e-2	Learning rate for the optax Adam optimiser.
optax_clip	float	1.0	Gradient clipping threshold.
alias	str	"ETS"	Display name for the model.
prediction_intervals	ConformalIntervals or None	None	Configuration for conformal prediction intervals. When provided, conformity scores are cached at :meth:fit time.

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

Fit the ETS model to a univariate time series.

Optimises smoothing parameters and initial states via optax gradient descent on the likelihood, then stores the full model state in :attr:model_.

Parameters:

Parameter	Type	Default	Description
y	jnp.ndarray	-	One-dimensional time series of shape (n,).
X	Optional[jnp.ndarray]	None	Ignored — present for API compatibility with :class:BaseForecaster.

Returns: Self (the fitted forecaster; sets self.model_).

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

Generate h-step-ahead forecasts from the fitted model.

Parameters:

Parameter	Type	Default	Description
h	int	-	Forecast horizon.
X	Optional[jnp.ndarray]	None	Ignored — present for API compatibility.
level	Optional[List[int]]	None	Confidence levels in [0, 100]. When provided and conformal_params is set, conformal intervals are returned; otherwise native Gaussian ETS intervals are used.

Returns: dict (Always contains "mean" of shape (h,). When level is given, also contains "lo-{level}" and "hi-{level}" for each requested level.) Raises: Exception (If called before :meth:fit.)

predict_in_sample(self, level=None) -> dict

Return in-sample fitted values (and optional prediction intervals).

Fitted values are one-step-ahead predictions for the training data, useful for computing residuals and evaluating goodness of fit.

Parameters:

Parameter	Type	Default	Description
level	Optional[List[int]]	None	Confidence levels in [0, 100]. When provided, symmetric ±z·σ intervals are appended using the residual standard error.

Returns: dict ({"fitted": jnp.ndarray} of shape (n,). When level is given, also contains "fitted-lo-{level}" and "fitted-hi-{level}" keys.) Raises: Exception (If called before :meth:fit.)

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

Stateless fit-and-predict in a single call.

Fits the ETS model to y and immediately produces h-step-ahead forecasts without persisting any model state on the instance. Ideal for cross-validation loops and batch evaluation.

Parameters:

Parameter	Type	Default	Description
y	jnp.ndarray	-	One-dimensional time series of shape (n,).
h	int	-	Forecast horizon.
X	Optional[jnp.ndarray]	None	Ignored — present for API compatibility.
X_future	Optional[jnp.ndarray]	None	Ignored — present for API compatibility.
level	Optional[List[int]]	None	Confidence levels in [0, 100] for prediction intervals.
fitted	bool	False	If True, the returned dict also includes "fitted" (in-sample predictions of shape (n,)).

Returns: dict (Always contains "mean" of shape (h,). Optionally includes "fitted", "lo-{level}", "hi-{level}", "fitted-lo-{level}", and "fitted-hi-{level}".)

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

Apply the previously fitted model structure to a new series.

Reuses the model specification (error/trend/season type, damping, etc.) learned by :meth:fit and re-estimates parameters on y via forward_ets. This is useful for walk-forward evaluation where the model structure is fixed but re-fitted on expanding windows.

Parameters:

Parameter	Type	Default	Description
y	jnp.ndarray	-	New time series of shape (n,).
h	int	-	Forecast horizon.
X	Optional[jnp.ndarray]	None	Ignored — present for API compatibility.
X_future	Optional[jnp.ndarray]	None	Ignored — present for API compatibility.
level	Optional[List[int]]	None	Confidence levels in [0, 100] for prediction intervals.
fitted	bool	False	If True, include in-sample fitted values in the output.

Returns: dict (Same structure as :meth:forecast.) Raises: Exception (If called before :meth:fit.)