TSB

chronax.models.tsb.TSB · inherits BaseForecaster

A forecaster designed for intermittent demand time series, implementing exponential smoothing on both the demand probability and the magnitude of non-zero demands (similar to Croston's method or TSB).

Class Attributes:

Attribute	Type	Description
uses_exog	bool	Indicates whether the model utilizes exogenous variables (False).
alias	str	The short name or alias for the model.
conformal_params	ConformalIntervals \| None	Configuration for conformal prediction intervals.
model_	dict | None	Stores the fitted model parameters after calling fit().

__init__(self, alpha_d: float, alpha_p: float, alias: str = "TSB", conformal_params: ConformalIntervals | None = None)

Initializes the TSB model with smoothing parameters for demand magnitude and probability.

Parameter	Type	Default	Description
alpha_d	float	-	Smoothing parameter for the demand magnitude. Must be in the range (0, 1).
alpha_p	float	-	Smoothing parameter for the demand probability. Must be in the range (0, 1).
alias	str	"TSB"	(undocumented)
conformal_params	ConformalIntervals \| None	None	(undocumented)

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

Fits the TSB model parameters (demand level, probability level, and residual sigma) to the historical time series y.

Parameter	Type	Default	Description
y	jnp.ndarray	-	The historical time series data.
X	jnp.ndarray \| None	None	Exogenous variables (ignored).

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

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

Generates forecasts for h steps ahead using the fitted model parameters.

Parameter	Type	Default	Description
h	int	-	The forecast horizon.
X	jnp.ndarray \| None	None	Exogenous variables (ignored).
level	list[int] \| None	None	List of confidence levels (e.g., [80, 95]) for prediction intervals.

Returns: dict containing the forecasts.

Key	Type	Description
"mean"	jnp.ndarray	The point forecasts of shape (h,).
"lo-<level>"	jnp.ndarray	Lower bound for the specified confidence level (if level is provided).
"hi-<level>"	jnp.ndarray	Upper bound for the specified confidence level (if level is provided).

Raises:

Exception	Description
ValueError	If fit() has not been called.

predict_in_sample(self, level: list[int] | None = None) -> dict

Generates in-sample fitted values based on the training data.

Parameter	Type	Default	Description
level	list[int] \| None	None	List of confidence levels (e.g., [80, 95]) for fitted intervals.

Returns: dict containing the fitted values.

Key	Type	Description
"fitted"	jnp.ndarray	The one-step-ahead fitted values.
"fitted-lo-<level>"	jnp.ndarray	Lower bound for the fitted interval (if level is provided).
"fitted-hi-<level>"	jnp.ndarray	Upper bound for the fitted interval (if level is provided).

Raises:

Exception	Description
ValueError	If fit() has not been called.

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

Performs a one-shot forecast without updating the internal state of the model. This method calculates the final state from y and then forecasts h steps ahead.

Parameter	Type	Default	Description
y	jnp.ndarray	-	The historical time series data used to initialize the state.
h	int	-	The forecast horizon.
X	jnp.ndarray \| None	None	Exogenous variables corresponding to y (ignored).
X_future	jnp.ndarray \| None	None	Exogenous variables for the forecast horizon (ignored).
level	list[int] \| None	None	List of confidence levels (e.g., [80, 95]) for prediction intervals.
fitted	bool	False	If True, returns in-sample fitted values in the output dictionary.

Returns: dict containing the forecasts.

Key	Type	Description
"mean"	jnp.ndarray	The point forecasts of shape (h,).
"fitted"	jnp.ndarray	The one-step-ahead fitted values (if fitted=True).
"lo-<level>"	jnp.ndarray	Lower bound for the specified confidence level (if level is provided).
"hi-<level>"	jnp.ndarray	Upper bound for the specified confidence level (if level is provided).
"fitted-lo-<level>"	jnp.ndarray	Lower bound for the fitted interval (if level and fitted=True are provided).
"fitted-hi-<level>"	jnp.ndarray	Upper bound for the fitted interval (if level and fitted=True are provided).

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

Alias for the forecast method, performing a stateless forecast based on the provided data y.

Parameter	Type	Default	Description
y	jnp.ndarray	-	The historical time series data used to initialize the state.
h	int	-	The forecast horizon.
X	jnp.ndarray \| None	None	Exogenous variables corresponding to y (ignored).
X_future	jnp.ndarray \| None	None	Exogenous variables for the forecast horizon (ignored).
level	list[int] \| None	None	List of confidence levels (e.g., [80, 95]) for prediction intervals.
fitted	bool	False	If True, returns in-sample fitted values in the output dictionary.

Returns: dict (Same structure as forecast).