AutoTBATS

chronax.models.tbats_model.AutoTBATS · inherits BaseForecaster

Automatic TBATS forecaster with model selection. TBATS decomposes a time series into level, trend, and one or more seasonal components represented by trigonometric (Fourier) terms, with optional Box–Cox variance stabilisation and ARMA residual modelling. AutoTBATS evaluates a grid of configurations (Box–Cox on/off, trend on/off, damped trend on/off, ARMA on/off) and selects the model that minimises AIC.

Attributes:

• uses_exog: bool (False)
• model_: dict or None — Full model state after :meth:fit, including estimated parameters, fitted values, residuals, AIC, Box–Cox λ, etc.
• only_conformal_intervals: bool (False) — this model supports both native Gaussian intervals and conformal intervals.

__init__(self, season_length, use_boxcox=None, bc_lower_bound=-1.0, bc_upper_bound=2.0, use_trend=None, use_damped_trend=None, use_arma_errors=False, alias='AutoTBATS', conformal_params=None)

Initialize the AutoTBATS estimator configuration.

Parameter	Type	Default	Description
season_length	Union[int, List[int]]	-	Seasonal period(s). Pass a single int for one seasonal cycle (e.g. 12 for monthly) or a list for multi-seasonality (e.g. [7, 365] for daily data with weekly + annual cycles).
use_boxcox	Optional[bool]	None	Whether to apply a Box–Cox transformation. None tries both on and off during model selection.
bc_lower_bound	float	-1.0	Lower bound for the Box–Cox λ parameter.
bc_upper_bound	float	2.0	Upper bound for the Box–Cox λ parameter.
use_trend	Optional[bool]	None	Whether to include a trend component. None tries both.
use_damped_trend	Optional[bool]	None	Whether to damp the trend. None tries both.
use_arma_errors	bool	False	Whether to add ARMA structure on the residuals.
alias	str	"AutoTBATS"	Display name for the model.
conformal_params	Optional[ConformalIntervals]	None	Configuration for conformal prediction intervals.

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

Fit the TBATS model to training data. Runs the full model-selection grid (Box–Cox, trend, damping, ARMA) and stores the winning configuration in :attr:model_.

Parameters:

Parameter	Type	Default	Description
y	jnp.ndarray	-	One-dimensional time series of shape (n,). Must be finite; if use_boxcox is enabled, values must be strictly positive.
X	Optional[jnp.ndarray]	None	Ignored — present for API compatibility.

Returns: Self (the fitted forecaster; sets self.model_). Raises: * ValueError: If y contains NaN or Inf values. * RuntimeWarning: If the sample is short relative to the largest seasonal period.

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

Return in-sample fitted values (and optional prediction intervals). Fitted values live on the model (working) scale. When Box–Cox was used during :meth:fit, they are automatically back-transformed to the original scale before being returned.

Parameters:

Parameter	Type	Default	Description
level	Optional[Tuple[int, ...]]	None	Confidence levels in [0, 100]. When provided, symmetric intervals are built around the fitted values using the residual standard error, and monotonicity (lo ≤ fitted ≤ hi) is enforced.

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

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

Generate h-step-ahead forecasts from the fitted model. When Box–Cox is active, prediction intervals are built on the transform scale (centred at mean_bc) and then inverted back to the original scale. Monotonicity (lo ≤ mean ≤ hi) is enforced to handle ULP edge cases when σ(h) ≈ 0.

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] for prediction intervals.

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

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

Stateless fit-and-predict in a single call. Runs the full model-selection grid on y, produces h-step-ahead forecasts, and (optionally) returns in-sample fitted values and prediction intervals. The fitted model is stored in :attr:model_ as a side effect for downstream inspection.

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, include in-sample fitted values (back-transformed when Box–Cox is active) in the output under "fitted".

Returns: dict. Always contains "mean" of shape (h,). Optionally includes "fitted", "lo-{level}", "hi-{level}", "fitted-lo-{level}", and "fitted-hi-{level}". Raises: * ValueError: If y contains NaN or Inf values.

TBATS

chronax.models.tbats_model.TBATS · inherits AutoTBATS

Fixed-configuration TBATS forecaster. A convenience subclass of :class:AutoTBATS with sensible defaults for a single, fully specified TBATS configuration: Box–Cox on (use_boxcox=True), Trend on (use_trend=True), Damping off (use_damped_trend=False), ARMA errors off (use_arma_errors=False). Because the configuration is fixed, no model-selection grid is evaluated — :meth:fit trains a single candidate model.

__init__(self, season_length, use_boxcox=True, bc_lower_bound=-1.0, bc_upper_bound=2.0, use_trend=True, use_damped_trend=False, use_arma_errors=False, alias='TBATS', conformal_params=None)

Initialize a fixed-configuration TBATS estimator.

Parameter	Type	Default	Description
season_length	Union[int, List[int]]	-	Seasonal period(s).
use_boxcox	Optional[bool]	True	Apply Box–Cox transformation.
bc_lower_bound	float	-1.0	Lower bound for the Box–Cox λ parameter.
bc_upper_bound	float	2.0	Upper bound for the Box–Cox λ parameter.
use_trend	Optional[bool]	True	Include a trend component.
use_damped_trend	Optional[bool]	False	Damp the trend toward zero.
use_arma_errors	bool	False	Add ARMA structure on the residuals.
alias	str	"TBATS"	Display name for the model.
conformal_params	Optional[ConformalIntervals]	None	Configuration for conformal prediction intervals.