ets_f

chronax.ets_functions.ets_f

Top-level ETS entry-point: automatic model selection and fitting.

When model is a three-character string (e.g. "ZZZ"), every "Z" is expanded into a grid of candidate component types. Each candidate is fitted via :func:etsmodel and scored by the chosen information criterion; the winner is returned.

When model is a dict (a previously-fitted result), this function acts as a forward step — rolling the stored parameters over new data without re-optimisation.

Parameter	Type	Default	Description
y	jnp.ndarray	-	Time series (cast to float64 internally).
m	int	-	Seasonal period (1 for non-seasonal data).
model	str \| dict[str, Any]	"ZZZ"	"ZZZ" for full auto-selection, a fixed spec like "AAN" for a single fit, or a previously-fitted dict for the forward path.
damped	Optional[bool]	None	None → try both damped and undamped; True / False → fix the choice.
alpha	Optional[float]	None	None → optimise; provide a float to fix the value.
beta	Optional[float]	None	None → optimise; provide a float to fix the value.
gamma	Optional[float]	None	None → optimise; provide a float to fix the value.
phi	Optional[float]	None	None → optimise; provide a float to fix the value.
additive_only	Optional[bool]	None	If True, forbid all multiplicative component types.
blambda	Any	None	(Not implemented — Box-Cox / bias-adjustment placeholders.)
biasadj	Any	None	(Not implemented — Box-Cox / bias-adjustment placeholders.)
lower	Optional[jnp.ndarray]	None	Box bounds for [α, β, γ, φ]; sensible defaults applied when None.
upper	Optional[jnp.ndarray]	None	Box bounds for [α, β, γ, φ]; sensible defaults applied when None.
opt_crit	str	"lik"	Optimisation objective ("lik" / "mse" / "amse" / "sigma" / "mae").
nmse	int	3	AMSE tracking horizon (1–30).
bounds	str	"both"	Bound mode ("both" / "usual" / "admissible").
ic	str	"aicc"	Information criterion for model selection ("aicc" / "aic" / "bic").
restrict	bool	True	Apply standard ETS combination restrictions (e.g. forbid MMA).
allow_multiplicative_trend	bool	False	Include "M" trend in the candidate grid.
use_initial_values	bool	False	(Reserved — not used.)
maxit	int	2_000	Maximum iteration budget passed to the optimiser.
optax_steps	Optional[int]	None	Explicit optax step count (None → auto-estimated from data).
optax_lr	float	1e-2	(undocumented)
optax_clip	float	1.0	(undocumented)
early_stop_patience	int	20	(undocumented)
early_stop_min_delta	float	1e-6	(undocumented)
allow_extended_iterations	bool	False	(undocumented)
adaptive_tol	bool	True	(undocumented)
pad_to	Optional[int]	None	(undocumented)
bucket_size	Optional[int]	None	(undocumented)

Returns: dict (Best-fitted model dictionary (see :func:etsmodel) with an added "method" key, e.g. "ETS(A,Ad,M)".) Raises: ValueError (If no admissible model can be found, or if parameter bounds are inconsistent.)

etsmodel

chronax.ets_functions.etsmodel

Fit a single ETS specification to the data and return a result dict.

Parameter	Type	Default	Description
y	jnp.ndarray	-	Observed time series.
m	int	-	Seasonal period.
errortype	str	-	Fixed structure flags ("A" / "M" / "N").
trendtype	str	-	Fixed structure flags ("A" / "M" / "N").
seasontype	str	-	Fixed structure flags ("A" / "M" / "N").
damped	bool	-	Whether the trend is damped.
alpha	float	-	Starting / fixed smoothing parameters (NaN → optimise).
beta	float	-	Starting / fixed smoothing parameters (NaN → optimise).
gamma	float	-	Starting / fixed smoothing parameters (NaN → optimise).
phi	float	-	Starting / fixed smoothing parameters (NaN → optimise).
lower	jnp.ndarray	-	Box-constraint bounds (length 4).
upper	jnp.ndarray	-	Box-constraint bounds (length 4).
opt_crit	str	-	Optimisation objective ("lik" / "mse" / "amse" / "sigma" / "mae").
nmse	int	-	AMSE horizon (1–30).
bounds	str	-	Bound mode ("both" / "usual" / "admissible").
maxit	int	2_000	Maximum iterations passed to the optimiser.
optax_steps	int \| None	300	Explicit number of optax steps (None → auto-estimate).
optax_lr	float	1e-2	(undocumented)
optax_clip	float	1.0	(undocumented)
early_stop_patience	int	20	(undocumented)
early_stop_min_delta	float	1e-6	(undocumented)
adaptive_tol	bool	True	(undocumented)
is_final_model	bool	False	(undocumented)
control	Any	None	(undocumented)
seed	Any	None	(undocumented)
trace	bool	False	(undocumented)
pad_to	Optional[int]	None	(undocumented)
bucket_size	Optional[int]	None	(undocumented)
stabilize	bool	True	(undocumented)
pure_sigmoid	bool	False	(undocumented)
selection_mode	bool	False	If True, skip state-history storage (fast path for model selection; fitted and states will be None).
init_state_override	jnp.ndarray \| None	None	(undocumented)

Returns: dict (Keys: loglik, aic, bic, aicc, mse, amse, sigma2, fit, residuals, fitted, components, m, nstate, states, par, n_params.)

etssimulate

chronax.ets_functions.etssimulate

Simulate h-step future sample paths from a given ETS state.

Parameter	Type	Default	Description
x	jnp.ndarray	-	State vector (level [+ trend] [+ seasonal]).
m	int	-	Seasonal period.
error	_ets.Component	-	Model structure flags.
trend	_ets.Component	-	Model structure flags.
season	_ets.Component	-	Model structure flags.
alpha	float	-	Smoothing parameters.
beta	float	-	Smoothing parameters.
gamma	float	-	Smoothing parameters.
phi	float	-	Smoothing parameters.
h	int	-	Forecast horizon.
y	jnp.ndarray	-	Pre-allocated output buffer (unused — kept for API parity).
e	jnp.ndarray	-	Innovation draws of length h (e.g. from N(0, σ)).

Returns: jnp.ndarray (Simulated future path of length h.)

etsforecast

chronax.ets_functions.etsforecast

Produce h-step-ahead forecasts from a state snapshot.

Parameter	Type	Default	Description
x	jnp.ndarray	-	State vector (level [+ trend] [+ m seasonal]).
m	int	-	Seasonal period (>=1).
trend	_ets.Component	-	Structural flags for trend/seasonality.
season	_ets.Component	-	Structural flags for trend/seasonality.
phi	float	-	Damping parameter (ignored if no trend).
h	int	-	Number of steps to forecast.
f	jnp.ndarray	-	Optional preallocated buffer (length h); created if None/wrong shape.

Returns: jnp.ndarray (Forecasts of shape (h,).)

initparam

chronax.ets_functions.initparam

Initialize (and lightly sanitize) smoothing parameters and bounds.

Parameter	Type	Default	Description
alpha	float	-	Optional user-provided starting values (use NaN to auto-init).
beta	float	-	Optional user-provided starting values (use NaN to auto-init).
gamma	float	-	Optional user-provided starting values (use NaN to auto-init).
phi	float	-	Optional user-provided starting values (use NaN to auto-init).
trendtype	str	-	Structure flags as strings for convenience.
seasontype	str	-	Structure flags as strings for convenience.
damped	bool	-	Whether a damped trend is considered.
lower	jnp.ndarray	-	4-element arrays of lower/upper bound suggestions.
upper	jnp.ndarray	-	4-element arrays of lower/upper bound suggestions.
m	int	-	Seasonal period.
bounds	str	-	Bound mode (admissible relaxes early to allow search to start).

Returns: (dict, jnp.ndarray, jnp.ndarray) (Dict of possibly-updated {alpha,beta,gamma,phi}, and the (possibly clipped) lower/upper arrays actually used.) Raises: Exception (Inconsistent parameter boundaries)

initstate

chronax.ets_functions.initstate

Initialize ETS states (level [+ trend] [+ seasonal]) from data.

Parameter	Type	Default	Description
y	jnp.ndarray	-	(undocumented)
m	int	-	(undocumented)
trendtype	str	-	(undocumented)
seasontype	str	-	(undocumented)

Returns: jnp.ndarray (Concatenated initial state vector.) Raises: ValueError (You've got to be joking (not enough data).), Exception (Multiplicative seasonality is not appropriate for zero and negative values)

admissible

chronax.ets_functions.admissible

Check ETS smoothing parameters against standard admissibility conditions.

Parameter	Type	Default	Description
alpha	float	-	(undocumented)
beta	float	-	(undocumented)
gamma	float	-	(undocumented)
phi	float	-	(undocumented)
m	int	-	(undocumented)

Returns: bool (True if parameter tuple passes admissibility checks.)

check_param

chronax.ets_functions.check_param

Validate smoothing parameters against box bounds and (optionally) admissibility.

Parameter	Type	Default	Description
alpha	float	-	Candidate smoothing parameters (NaN for unused, e.g., when no season).
beta	float	-	Candidate smoothing parameters (NaN for unused, e.g., when no season).
gamma	float	-	Candidate smoothing parameters (NaN for unused, e.g., when no season).
phi	float	-	Candidate smoothing parameters (NaN for unused, e.g., when no season).
lower	jnp.ndarray	-	Elementwise lower/upper bounds (length 4).
upper	jnp.ndarray	-	Elementwise lower/upper bounds (length 4).
bounds	str	-	If not "admissible", enforce box bounds; if not "usual", enforce ETS admissibility.
m	int	-	Seasonal period.

Returns: bool (True if parameters are within range and admissible per bounds.)

fourier

chronax.ets_functions.fourier

Build a simple Fourier design matrix for seasonality.

Parameter	Type	Default	Description
x	Any	-	Input series (used only for length alignment).
period	list[int]	-	Seasonal periods to include (e.g., [m]).
K	list[int]	-	Number of harmonics per period.
h	Optional[int]	None	If provided, build the matrix for the future h steps; else fit window.

Returns: jnp.ndarray (Matrix with sin/cos columns for selected harmonics, with degenerate sinpi=0 columns removed.)

pegelsfcast_C

chronax.ets_functions.pegelsfcast_C

One-step call to produce the mean forecast path from a fitted model dict.

Parameter	Type	Default	Description
h	int	-	Horizon.
obj	dict[str, Any]	-	Fitted model dictionary from etsmodel / ets_f.
npaths	Optional[int]	None	unused
level	Optional[list[int]]	None	unused
bootstrap	Optional[bool]	None	unused

Returns: jnp.ndarray (Mean forecast of length h.)

forecast_ets

chronax.ets_functions.forecast_ets

Convenience wrapper: produce forecasts (and optional PI) from fitted model.

Parameter	Type	Default	Description
obj	dict[str, Any]	-	Fitted model dictionary returned by ets_f/etsmodel.
h	int	-	Horizon.
level	Optional[list[int]]	None	Confidence levels (e.g., [80, 95]) for prediction intervals.

Returns: dict (Keys: "mean", "residuals", "fitted", and optionally "lo-XX"/"hi-XX".)

forward_ets

chronax.ets_functions.forward_ets

Roll a previously fitted ETS model forward on new data.

Parameter	Type	Default	Description
fitted_model	dict	-	Output of :func:ets_f / :func:etsmodel (must contain "m", "components", "par", "fit", "n_params").
y	jnp.ndarray	-	New time series segment.

Returns: dict (Fresh model dict with updated residuals, fitted values, and states computed on y, but the same structure and parameters.)

switch

chronax.ets_functions.switch

Map a single-character component string to the :class:ets_backend.Component enum.

Parameter	Type	Default	Description
x	str	-	One of "N" (Nothing), "A" (Additive), "M" (Multiplicative).

Returns: _ets.Component Raises: ValueError (If x is not a recognised flag.)

switch_criterion

chronax.ets_functions.switch_criterion

Map an objective string to the :class:ets_backend.Criterion enum.

Parameter	Type	Default	Description
x	str	-	One of "lik", "mse", "amse", "sigma", "mae".

Returns: _ets.Criterion Raises: ValueError (If x is not a recognised objective name.)