CESParams

ces.CESParams

Parameters for Complex Exponential Smoothing model variants.

This dataclass holds the smoothing parameters for different CES model variants. The complex-valued smoothing parameter is $\alpha_{complex} = \alpha_0 + i\alpha_1$, which controls how the state rotates in the complex plane. Seasonal damping parameters ($\beta_0, \beta_1$) are used only in PARTIAL and FULL variants.

Attributes

Attribute	Type	Default	Description
alpha_0	float	1.3	Real component of complex smoothing parameter.
alpha_1	float	1.0	Imaginary component of complex smoothing parameter.
beta_0	Optional[float]	None	Seasonal damping parameter for PARTIAL/FULL variants. In PARTIAL: controls simple seasonal damping. In FULL: real component of complex seasonal damping.
beta_1	Optional[float]	None	Seasonal damping parameter for FULL variant only. Imaginary component of complex seasonal damping.

for_variant(cls, variant: int) -> CESParams

Create default CESParams for a given model variant.

Returns appropriate default parameters based on the seasonal variant: - NONE (0): alpha_0=1.3, alpha_1=1.0 - SIMPLE (1): alpha_0=1.3, alpha_1=1.0 - PARTIAL (2): alpha_0=1.3, alpha_1=1.0, beta_0=0.1 - FULL (3): alpha_0=1.3, alpha_1=1.0, beta_0=1.3, beta_1=1.0

Parameter	Type	Default	Description
variant	int	-	Model variant identifier. One of: NONE (0), SIMPLE (1), PARTIAL (2), FULL (3).

Returns: CESParams instance with appropriate defaults for the variant.

to_dict(self) -> Dict

Convert parameters to dictionary format.

Returns: Dict with keys: 'alpha_0', 'alpha_1', 'beta_0', 'beta_1'.

auto_ces

ces.auto_ces

Fit CES with automatic or fixed model selection.

When model="Z", fits all applicable variants (NONE always; SIMPLE/PARTIAL/FULL when n >= 2*m) and returns the fit with the lowest information criterion. Otherwise, fits the specified variant directly.

Parameter	Type	Default	Description
y	jnp.ndarray	-	Time series of shape (n,).
m	int	1	Seasonal period. Default is 1 (no seasonality).
model	str	'Z'	Variant selector. "Z" for automatic selection; one of "N", "S", "P", "F" to fix the variant.
ic	str	'aicc'	Information criterion used for model selection when model="Z". One of "aic", "bic", "aicc".

Returns: Dict from ces_fit_single() for the selected variant, containing fitted values, residuals, states, parameters, and information criteria.

Raises: * ValueError: If model="Z" and no variant could be fitted successfully.

AutoCES

ces.AutoCES · inherits BaseForecaster

Complex Exponential Smoothing model with optional automatic variant selection.

Wraps auto_ces / ces_fit_single in the BaseForecaster interface. When model="Z", selects the best variant (NONE/SIMPLE/PARTIAL/FULL) by AICc. All JAX core functions are JIT-compiled; the class itself is a thin orchestrator.

Attributes: * uses_exog: False * alias: Model name for display / repr. * conformal_params: Conformal prediction configuration for generating prediction intervals. * model_: dict | None. Populated after fit(); contains fitted values, residuals, states, parameters, and information criteria from ces_fit_single(). None before first fit.

__init__(self, season_length: int = 1, model: str = 'Z', alias: str = 'CES', conformal_params: Optional[ConformalIntervals] = None) -> None

Initialise AutoCES with model configuration.

Parameter	Type	Default	Description
season_length	int	1	Seasonal period m. Use 1 for non-seasonal data.
model	str	'Z'	Variant selector ("Z", "N", "S", "P", "F").
alias	str	'CES'	Model name identifier.
conformal_params	Optional[ConformalIntervals]	None	Conformal prediction configuration.

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

Fit the CES model to a time series.

Handles the constant-series edge case separately (stores a trivial state). Otherwise delegates to auto_ces() which runs variant selection and back-fitting.

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

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

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

Stateless fit+forecast: fit if not already done, then generate forecasts.

If model_ is None, fits the model on y first. Otherwise uses existing state. Does not support conformal intervals (use predict() after fit() for that).

Parameter	Type	Default	Description
y	jnp.ndarray	-	Input time series of shape (n,). Used only if not fitted.
h	int	-	Forecast horizon (number of steps ahead).
X	Optional[jnp.ndarray]	None	Exogenous variables (unused).
X_future	Optional[jnp.ndarray]	None	Future exogenous variables (unused).
level	Optional[List[int]]	None	Confidence levels (unused; included for BaseForecaster compliance).
fitted	bool	False	Whether to return fitted values (unused; included for BaseForecaster compliance).

Returns: Dict containing: {"mean": jnp.ndarray} (forecasts of shape (h,)).

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

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

Runs the JIT-compiled ces_forecast() function from the stored final state. Handles the constant-series edge case (alpha=0) by returning flat forecasts. Optionally adds conformal prediction intervals.

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

Returns: Dict containing: * "mean": Point forecasts of shape (h,). * "lo-{l}" / "hi-{l}": Conformal interval bounds for each level l (only present when level is not None and conformal_params is set).

Raises: * ValueError: If called before fit().