BaseForecaster

chronax.base_forecaster.BaseForecaster · inherits ABC

Abstract base class defining the shared interface for all Chronax forecasting models.

All models must implement fit, predict, and forecast. See module docstring for full attribute and method documentation.

Attributes: * alias: model name, declared in model's __init__. * conformal_params: a conformal_intervals object (previously named prediction_intervals). * model_: stores fitted model post-training. * uses_exog: boolean representing model's exogenous variable handling (Class attribute, defaults to False).

new(self) -> BaseForecaster

Return a shallow copy of this model instance.

Used internally to clone a model without mutating shared state.

Returns: BaseForecaster (A new instance of the same type with a shallow-copied __dict__.)

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

Fit the model to univariate time series y. Must set self.model_ and return self.

Parameter	Type	Default	Description
y	jnp.ndarray	-	Univariate time series.
X	jnp.ndarray | None	None	Optional exogenous input.

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

predict(self, h: int, X: jnp.ndarray | None = None, level: list[int | float] | None = None) -> dict

Generate h-step-ahead forecasts. Returns a dict with at least {"mean": jnp.ndarray}.

Parameter	Type	Default	Description
h	int	-	(undocumented)
X	jnp.ndarray | None	None	(undocumented)
level	list[int | float] | None	None	(undocumented)

Returns: dict (A dictionary with at least {"mean": jnp.ndarray}.)

forecast(self, y: jnp.ndarray, h: int, X: jnp.ndarray | None = None, X_future: jnp.ndarray | None = None, level: list[int | float] | None = None, fitted: bool = False) -> dict

Stateless fit+predict on y, forecasting h steps ahead. Must return a dict with at least {"mean": jnp.ndarray}. Subclasses may extend the signature with model-specific optional parameters.

Parameter	Type	Default	Description
y	jnp.ndarray	-	(undocumented)
h	int	-	(undocumented)
X	jnp.ndarray | None	None	(undocumented)
X_future	jnp.ndarray | None	None	(undocumented)
level	list[int | float] | None	None	(undocumented)
fitted	bool	False	(undocumented)

Returns: dict (A dictionary with at least {"mean": jnp.ndarray}.)

forward(self, y: jnp.ndarray, h: int, X: jnp.ndarray | None = None, X_future: jnp.ndarray | None = None, level: list[int | float] | None = None, fitted: bool = False) -> dict

Update the model on new data y and forecast h steps ahead. Default delegates to forecast(). Subclasses with warm-start behavior (e.g. Holt, HoltWinters, ETS) override this.

Parameter	Type	Default	Description
y	jnp.ndarray	-	(undocumented)
h	int	-	(undocumented)
X	jnp.ndarray | None	None	(undocumented)
X_future	jnp.ndarray | None	None	(undocumented)
level	list[int | float] | None	None	(undocumented)
fitted	bool	False	(undocumented)

Returns: dict (undocumented)

conformity_scores(self, y: jnp.ndarray, X: jnp.ndarray | None = None) -> jnp.ndarray

Compute signed conformity scores via walk-forward cross-validation.

Scores are signed residuals (actual - forecast) across n_windows expanding windows of horizon h. Uses vmap for parallelization. The interval construction method determines how scores are used: conformal_distribution takes their absolute value for symmetric intervals; conformal_signed uses them directly for asymmetric intervals.

Parameter	Type	Default	Description
y	jnp.ndarray	-	Univariate time series of observed values.
X	jnp.ndarray | None	None	Exogenous features array, shape (n_samples, n_features). Only used by models where uses_exog=True.

Returns: jnp.ndarray (2-D array of shape (n_windows, h) containing signed forecast errors for each window and horizon step.) Raises: ValueError (If conformal_params is None.) Raises: ValueError (If the series is too short to form at least 2 windows.)

add_confidence_intervals(fcst: dict, cs: jnp.ndarray, level: list[int | float], method: str) -> dict

Add conformal prediction intervals to a forecast dict.

Mutates and returns fcst with interval columns added in-place, keyed as "lo-{level}" and "hi-{level}" for each requested level.

Parameter	Type	Default	Description
fcst	dict	-	Forecast dictionary containing at least {"mean": jnp.ndarray}.
cs	jnp.ndarray	-	Signed conformity scores, shape (n_windows, h).
level	list[int | float]	-	Confidence levels, e.g. [80, 95].
method	str	-	"conformal_distribution" (symmetric, uses |scores|) or "conformal_signed" (asymmetric, uses raw signed scores).

Returns: dict (The input fcst dict with interval arrays added.) Raises: ValueError (If method is not a recognised conformal method.)