SeasonalExponentialSmoothing

chronax.models.seasonal_exponential_smoothing · inherits BaseForecaster

Seasonal Exponential Smoothing (SES) applies Simple Exponential Smoothing independently to each seasonal subseries (i.e. each phase of the cycle). The forecast for horizon $h$ is a tiled repetition of per-season SES forecasts, making it suitable for data with stable seasonal patterns and no clear trend. It uses a weighted average of all past observations where the weights decrease exponentially into the past.

Attributes

Attribute	Type	Description
season_length	int	Number of observations per seasonal cycle.
alpha	float	Smoothing parameter shared across all seasons ($0 \le \alpha \le 1$).
alias	str	Model identifier string ("SeasonalES").
prediction_intervals	Optional[ConformalIntervals]	Information for computing conformal prediction intervals.
conformal_params	Optional[ConformalIntervals]	Alias for prediction_intervals (for BaseForecaster compatibility).
only_conformal_intervals	bool	Always True (no native parametric intervals).

__init__(self, season_length: int, alpha: float, alias: str = 'SeasonalES', prediction_intervals: Optional[ConformalIntervals] = None)

Initializes the Seasonal Exponential Smoothing model parameters.

Parameter	Type	Default	Description
season_length	int	-	Number of observations per unit of time. Ex: 24 Hourly data.
alpha	float	-	Smoothing parameter.
alias	str	"SeasonalES"	Custom name of the model.
prediction_intervals	Optional[ConformalIntervals]	None	Information to compute conformal prediction intervals. This is required for generating future prediction intervals.

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

Fit the SeasonalExponentialSmoothing model.

Applies per-season SES to the input series and stores the fitted seasonal pattern. If prediction_intervals is configured, conformity scores are also computed and cached for use in predict().

Parameters:

Parameter	Type	Default	Description
y	jnp.ndarray	-	Clean time series of shape (t,).
X	Optional[jnp.ndarray]	None	Exogenous variables (unused; included for API compatibility).

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

predict(self, h: int, X: Optional[jnp.ndarray] = None, level: Optional[List[int]] = None) -> Dict[str, jnp.ndarray]

Generate h-step ahead forecasts using the fitted model.

Tiles the stored per-season SES forecasts to cover the requested horizon. Optionally adds conformal prediction intervals.

Parameters:

Parameter	Type	Default	Description
h	int	-	Forecast horizon (number of steps ahead).
X	Optional[jnp.ndarray]	None	Exogenous variables (unused; included for API compatibility).
level	Optional[List[int]]	None	Confidence levels (0--100) for prediction intervals, e.g. [80, 95]. Requires prediction_intervals to be set.

Returns: Dict[str, jnp.ndarray] (Dictionary containing "mean" (point forecasts of shape (h,)) and optionally "lo-{l}" / "hi-{l}" (conformal interval bounds for each level l, only present when level is not None)).

Raises: * Exception: If level is requested but prediction_intervals is None.

predict_in_sample(self) -> Dict[str, jnp.ndarray]

Return in-sample fitted values from the last fit() call.

Parameters: None.

Returns: Dict[str, jnp.ndarray] (Dictionary containing: "fitted": In-sample predictions of shape (t,).).

forecast(self, y: jnp.ndarray, h: int, X: Optional[jnp.ndarray] = None, X_future: Optional[jnp.ndarray] = None, level: Optional[List[int]] = None, fitted: bool = False) -> Dict[str, jnp.ndarray]

Memory-efficient stateless fit+predict in one call.

Fits the model on y and immediately generates forecasts without storing any model state. Useful for cross-validation loops or one-shot forecasting.

Parameters:

Parameter	Type	Default	Description
y	jnp.ndarray	-	Clean time series of shape (t,).
h	int	-	Forecast horizon (number of steps ahead).
X	Optional[jnp.ndarray]	None	In-sample exogenous variables (unused; included for API compatibility).
X_future	Optional[jnp.ndarray]	None	Future exogenous variables (unused; included for API compatibility).
level	Optional[List[int]]	None	Confidence levels (0--100) for prediction intervals, e.g. [80, 95]. Requires prediction_intervals to be set.
fitted	bool	False	Whether to include in-sample fitted values in the output.

Returns: Dict[str, jnp.ndarray] (Dictionary containing "mean" (point forecasts of shape (h,)), "fitted" (in-sample fitted values of shape (t,), only if fitted=True), and optionally "lo-{l}" / "hi-{l}" (conformal interval bounds for each level l, only present when level is not None)).

Raises: * Exception: If level is requested but prediction_intervals is None.