MSTL

chronax.models.MSTL · inherits BaseForecaster

Multiple Seasonal-Trend decomposition using LOESS.

MSTL extends STL to handle time series with multiple seasonal patterns by iteratively extracting each seasonal component. For example, it can decompose data with both daily and weekly seasonality, or hourly, daily, and weekly patterns.

Attributes: * uses_exog: False * alias: str * conformal_params: ConformalIntervals | None * model_: dict (Populated after fit)

__init__(self, period, iterate=2, s_window=None, seasonal_deg=0, trend_deg=1, seasonal_jump=1, trend_jump=1, inner=1, trend_window=None, low_pass=None, tail_window=None, fitted=True, alias='MSTL', conformal_params=None)

Initializes the MSTL model configuration.

Parameter	Type	Default	Description
period	int | list[int]	-	Seasonal period(s) to extract. Can be a single integer or list of integers. Periods are sorted in ascending order internally. For example, [7, 365] for weekly and yearly seasonality.
iterate	int	2	Number of outer refinement iterations to improve decomposition. Ignored when only a single period is specified.
s_window	int | list[int] | None	None	Seasonal smoother window size(s), one per period. Must be odd. If None, defaults to [11, 15, 19, 23, 27, 31] for the first periods. If a single int, uses the same window for all periods.
seasonal_deg	int	0	Polynomial degree (0 or 1) for seasonal LOESS smoother.
trend_deg	int	1	Polynomial degree (0 or 1) for trend LOESS smoother.
seasonal_jump	int	1	Jump step for seasonal LOESS to speed up computation. Minimum value is 1.
trend_jump	int	1	Jump step for trend LOESS to speed up computation. Minimum value is 1.
inner	int	1	Number of inner STL iterations performed for each period extraction.
trend_window	int | None	None	Trend smoother window size. Must be odd. If None, derived automatically from the largest period as (2 * largest_period + 1) | 1.
low_pass	int | None	None	Low-pass filter window for seasonal stabilization. Must be odd if specified.
tail_window	int | None	None	Number of tail points to use for linear trend extrapolation in forecasting. If None, defaults to min(n, 2*largest_period+1) when periods exist, or max(5, n//10) otherwise.
fitted	bool	True	Whether to include decomposition components (trend, seasonals, remainder) in predict_in_sample output.
alias	str	"MSTL"	Model name identifier.
conformal_params	ConformalIntervals | None	None	Configuration for conformal prediction intervals. If None, no intervals are computed.

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

Fit MSTL decomposition to the input time series.

Performs iterative STL decomposition to extract multiple seasonal components, trend, and remainder. The decomposition is stored in self.model_ for use in prediction methods.

Parameters:

Parameter	Type	Default	Description
y	jnp.ndarray	-	Input time series data. Will be reshaped to 1D and converted to float.
X	jnp.ndarray | None	None	Exogenous variables (not used by MSTL, included for interface conformity).

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

predict_in_sample(self, X=None, level=None) -> dict

Generate in-sample fitted values and decomposition components.

Parameters:

Parameter	Type	Default	Description
X	jnp.ndarray | None	None	Exogenous variables (not used by MSTL).
level	list[int | float] | None	None	Confidence levels for conformal prediction intervals (e.g., [90, 95]). If None, no intervals are computed.

Returns: dict

Key	Type	Description
"mean"	jnp.ndarray	Fitted values (trend + all seasonals).
"fitted"	jnp.ndarray	Same as "mean" (included if self.fitted is True).
"trend"	jnp.ndarray	Extracted trend component (if self.fitted is True).
"seasonal" or "seasonal{p}"	jnp.ndarray	Seasonal component(s). Single period uses "seasonal", multiple periods use "seasonal{p}" where p is the period length (included if self.fitted is True).
"remainder"	jnp.ndarray	Residual component (if self.fitted is True).
"lo-{level}"	jnp.ndarray	Conformal prediction interval lower bound (if level is provided).
"hi-{level}"	jnp.ndarray	Conformal prediction interval upper bound (if level is provided).

predict(self, h, X=None, level=None) -> dict

Generate out-of-sample forecasts.

Forecasts are produced by linearly extrapolating the trend from tail points and repeating each seasonal pattern cyclically.

Parameters:

Parameter	Type	Default	Description
h	int	-	Forecast horizon (number of steps ahead).
X	jnp.ndarray | None	None	Exogenous variables for forecast period (not used by MSTL).
level	list[int | float] | None	None	Confidence levels for conformal prediction intervals (e.g., [90, 95]). If None, no intervals are computed.

Returns: dict

Key	Type	Description
"mean"	jnp.ndarray	Point forecasts (extrapolated trend + repeated seasonals).
"lo-{level}"	jnp.ndarray	Conformal prediction interval lower bound (if level is provided).
"hi-{level}"	jnp.ndarray	Conformal prediction interval upper bound (if level is provided).

forecast(self, y, h, X=None, X_future=None, level=None, fitted=False) -> dict

Fit and forecast in one step, used for conformity score computation.

Creates a new MSTL instance, fits it to the data, and generates forecasts. This method is primarily used internally for computing conformity scores in conformal prediction.

Parameters:

Parameter	Type	Default	Description
y	jnp.ndarray	-	Input time series data.
h	int	-	Forecast horizon (number of steps ahead).
X	jnp.ndarray | None	None	Exogenous variables for training period (not used by MSTL).
X_future	jnp.ndarray | None	None	Exogenous variables for forecast period (not used by MSTL).
level	int | tuple[int, ...] | None	None	Confidence levels for prediction intervals.
fitted	bool	False	Whether to return fitted values.

Returns: dict (Forecast dictionary with same structure as predict() output.)