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 α_complex = α_0 + i*α_1, which controls how the state rotates in the complex plane. Seasonal damping parameters (β_0, β_1) are used only in PARTIAL and FULL variants.

__init__(self, alpha_0: float = 1.3, alpha_1: float = 1.0, beta_0: Optional[float] = None, beta_1: Optional[float] = None)

Parameter	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.

Parameters:

Parameter	Type	Default	Description
variant	int	-	Model variant identifier. One of: NONE (0): No seasonality, SIMPLE (1): Simple seasonal component, PARTIAL (2): Partial seasonal damping, FULL (3): Full seasonal damping.

Returns: CESParams (CESParams instance with appropriate defaults for the variant).

to_dict(self) -> Dict

Convert parameters to dictionary format.

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

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) -> AutoCES

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 (Dictionary with key "mean" containing 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 (Dictionary 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()).

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 (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).

ces_fit_single

ces.ces_fit_single

Fit a single CES variant and return metrics, fitted values, and state.

Initialises the state vector, runs back-fitting, computes in-sample residuals, and calculates information criteria (AIC, BIC, AICc).

Parameter	Type	Default	Description
y	jnp.ndarray	-	Time series of shape (n,).
m	int	-	Seasonal period.
season_type	int	-	Model variant (NONE=0, SIMPLE=1, PARTIAL=2, FULL=3).
params	Optional[CESParams]	None	CESParams with smoothing parameters. If None, uses CESParams.for_variant(season_type) defaults.

Returns: Dict (Dictionary with keys: "loglik" (float): Log-likelihood. "aic" / "bic" / "aicc" (float): Information criteria. "mse" / "amse" (float): Mean squared error on y[m:]. "fitted" (jnp.ndarray): In-sample fitted values, shape (n,). "residuals" (jnp.ndarray): Residuals y[m:] − ŷ[m:], shape (n-m,). "states" (jnp.ndarray): Final state buffer, shape (m, 4). "par" (dict): Parameter dict from params.to_dict(). "m" (int): Seasonal period used. "n" (int): Series length. "seasontype" (int): Variant used. "sigma2" (float): Residual variance estimate.).