XLinear

chronax.models.XLinear · inherits BaseForecaster

Univariate XLinear forecaster (JAX/Flax-NNX port of neuralforecast.XLinear). Univariate adaptation of NF's multivariate gated-linear model: internal RevIN normalization (use_norm, on by default), a Linear projection to hidden_size, a learned global token, temporal gating over the concatenated embedding, cross-channel gating over the [embedding, global] pair, and a linear head. Defaults match neuralforecast 3.1.7 (hidden_size=128, temporal_ff=256, channel_ff=8, max_steps=1000, learning_rate=1e-3, windows_batch_size=32, identity scaler, MAE loss).

Maintenance status: Active univariate forecaster. Integrates with the BaseForecaster interface, including conformal prediction intervals via predict(level=...), pickle round-trip, and forecast(fitted=True).

__init__(self, h: int, input_size: int = -1, hidden_size: int = 128, temporal_ff: int = 256, channel_ff: int = 8, use_norm: bool = True, max_steps: int = 1000, learning_rate: Union[float, Callable[[int], float]] = 0.001, windows_batch_size: int = 32, loss: Union[str, LossFn] = 'mae', scaler: Union[str, Scaler] = 'identity', random_seed: int = 1, alias: str = 'XLinear')

Initializes the XLinear forecaster parameters.

Parameter	Type	Default	Description
h	int	-	Forecast horizon.
input_size	int	-1	Input window size. If any value less than 1, it expands to 3 * h.
hidden_size	int	128	Hidden layer size.
temporal_ff	int	256	Temporal feed-forward size.
channel_ff	int	8	Channel feed-forward size.
use_norm	bool	True	Whether to use internal RevIN normalization.
max_steps	int	1000	Maximum training steps.
learning_rate	Union[float, Callable[[int], float]]	1e-3	Learning rate or learning rate schedule function.
windows_batch_size	int	32	Batch size for windowed training.
loss	Union[str, LossFn]	"mae"	Loss function name (e.g., "mae") or callable.
scaler	Union[str, Scaler]	"identity"	Input scaler name ("identity" or "robust") or callable.
random_seed	int	1	Random seed for initialization and training.
alias	str	"XLinear"	Model alias.

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

Fit on a 1-D series. Raises NotImplementedError on exog; ValueError if y is not 1-D or shorter than input_size+h; RuntimeError on divergence.

Parameters:

Parameter	Type	Default	Description
y	jnp.ndarray	-	The univariate time series data (1-D).
X	jnp.ndarray \| None	None	Exogenous variables (not supported).

Returns: Self (the fitted forecaster; sets self.model_). Raises: NotImplementedError, ValueError.

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

Forecast h steps (1 <= h <= self.h). level -> inherited conformal path.

Parameters:

Parameter	Type	Default	Description
h	int	-	The number of steps to forecast. Must be less than or equal to self.h.
X	jnp.ndarray \| None	None	(undocumented)
level	list[int \| float] \| None	None	Confidence levels for prediction intervals (requires conformal_params to be set).

Returns: dict Return keys include: {"mean": jnp.ndarray}. If level is provided, keys for prediction intervals (e.g., lower_90, upper_90) are also included.

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-then-predict; fitted=True adds one-step-ahead fitted values.

Parameters:

Parameter	Type	Default	Description
y	jnp.ndarray	-	The history series to fit on.
h	int	-	The number of steps to forecast.
X	jnp.ndarray \| None	None	Exogenous variables (not supported).
X_future	jnp.ndarray \| None	None	Future exogenous variables (not supported).
level	list[int \| float] \| None	None	Confidence levels for prediction intervals.
fitted	bool	False	If True, compute and return one-step-ahead fitted values.

Returns: dict Return keys include: {"mean": jnp.ndarray}. If level is provided, prediction intervals are included. If fitted=True, {"fitted": jnp.ndarray} is also included.