STL

chronax.models.stl · inherits BaseForecaster

STL (Seasonal-Trend decomposition using LOESS) forecaster.

STL decomposes a time series into seasonal, trend, and remainder components using locally weighted regression (LOESS). The algorithm iteratively applies LOESS smoothing to extract seasonal patterns and trends, making it robust to outliers and capable of handling complex seasonal patterns.

The decomposition follows these steps: 1. Seasonal smoothing by subseries (each phase of the seasonal cycle) 2. Centering seasonal component to sum-to-zero constraint over each phase 3. Optional low-pass filtering for seasonal stabilization 4. Trend smoothing on deseasonalized data

For forecasting, STL extrapolates the trend linearly and repeats the seasonal pattern. Prediction intervals can be generated using conformal prediction.

Attributes

uses_exog: False alias: Model alias name for identification. conformal_params: Conformal prediction configuration. model_: Dictionary holding fitted components (y, seasonal, trend, remainder, period).

__init__(self, period, seasonal=None, trend=None, low_pass=None, seasonal_deg=0, trend_deg=1, seasonal_jump=1, trend_jump=1, inner=1, tail_window=None, fitted=True, alias='STL', conformal_params=None)

Initializes the STL forecaster configuration.

Parameter	Type	Default	Description
period	int	-	Seasonal period length (e.g., 7 for weekly, 12 for monthly with yearly seasonality).
seasonal	int \| None	None	Seasonal smoother window size (must be odd). If None, defaults to max(7, 2*period+1) made odd. Larger values produce smoother seasonal components.
trend	int \| None	None	Trend smoother window size (must be odd). If None, defaults to 2*period+1 made odd. Larger values produce smoother trends.
low_pass	int \| None	None	Low-pass filter window size for seasonal component (must be odd if provided). Defaults to None (no low-pass filtering). When set, stabilizes seasonal component.
seasonal_deg	int	0	Polynomial degree for seasonal LOESS (0=local constant, 1=local linear).
trend_deg	int	1	Polynomial degree for trend LOESS (0=local constant, 1=local linear).
seasonal_jump	int	1	Jump (stride) for seasonal LOESS anchor points to speed computation. Defaults to 1 (no jumping).
trend_jump	int	1	Jump (stride) for trend LOESS anchor points to speed computation. Defaults to 1 (no jumping).
inner	int	1	Number of inner loop iterations for iterative refinement of seasonal and trend. Higher values may improve decomposition quality.
tail_window	int \| None	None	Number of trailing points to use for trend extrapolation. If None, defaults to min(n, 2*period+1).
fitted	bool	True	Whether to include fitted values and decomposition components in predict_in_sample output.
alias	str	"STL"	Model alias name for identification.
conformal_params	"ConformalIntervals \| None"	None	Conformal prediction configuration for generating prediction intervals.

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

Fit the STL model by decomposing the time series.

Parameters:

Parameter	Type	Default	Description
y	jnp.ndarray	-	Input time series to decompose, shape (n,).
X	jnp.ndarray \| None	None	Exogenous variables (not used by STL, included for API compatibility).

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 STL, included for API compatibility).
level	list[int \| float] \| None	None	Confidence levels for prediction intervals (e.g., [90, 95]). If provided, conformal prediction intervals are computed.

Returns: dict

Key	Type	Description
mean	jnp.ndarray	In-sample fitted values (trend + seasonal), shape (n,).
fitted	jnp.ndarray	Same as mean, included if self.fitted=True.
trend	jnp.ndarray	Trend component, shape (n,), included if self.fitted=True.
seasonal	jnp.ndarray	Seasonal component, shape (n,), included if self.fitted=True.
remainder	jnp.ndarray	Remainder component, shape (n,), included if self.fitted=True.
lo-{level}	jnp.ndarray	Lower prediction interval for each level, if level is provided.
hi-{level}	jnp.ndarray	Upper prediction interval for each level, if level is provided.

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

Generate out-of-sample forecasts.

The forecast is computed by linearly extrapolating the trend component from the tail window and repeating the last seasonal cycle.

Parameters:

Parameter	Type	Default	Description
h	int	-	Forecast horizon (number of steps ahead to predict).
X	jnp.ndarray \| None	None	Exogenous variables (not used by STL, included for API compatibility).
level	list[int \| float] \| None	None	Confidence levels for prediction intervals (e.g., [90, 95]). If provided, conformal prediction intervals are computed.

Returns: dict

Key	Type	Description
mean	jnp.ndarray	Point forecasts, shape (h,).
lo-{level}	jnp.ndarray	Lower prediction interval for each level, if level is provided.
hi-{level}	jnp.ndarray	Upper prediction interval for each level, if level is provided.

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

Generate forecasts on fresh data for conformity score computation.

This method creates a new STL instance, fits it on the provided data, and generates predictions. It is used internally by BaseForecaster.conformity_scores to compute conformal prediction intervals.

Parameters:

Parameter	Type	Default	Description
y	jnp.ndarray	-	Time series to fit, shape (n,).
h	int	-	Forecast horizon (number of steps ahead to predict).
X	jnp.ndarray \| None	None	Exogenous variables for fitting (not used by STL).
X_future	jnp.ndarray \| None	None	Future exogenous variables for prediction (not used by STL).
level	int \| tuple[int, ...] \| None	None	Confidence levels for prediction intervals.
fitted	bool	False	Whether to return fitted values.

Returns: dict

Key	Type	Description
mean	jnp.ndarray	Point forecasts, shape (h,).

stl_decompose

chronax.models.stl

Perform STL decomposition using seasonal subseries LOESS and trend LOESS.

stl_decompose(y, period, seasonal, trend, low_pass=None, seasonal_deg=0, trend_deg=1, seasonal_jump=1, trend_jump=1, inner=1)

Parameter	Type	Default	Description
y	jnp.ndarray	-	Input time series to decompose, shape (n,).
period	int	-	Seasonal period length (e.g., 12 for monthly data with yearly seasonality).
seasonal	int	-	Seasonal smoother window size (must be odd).
trend	int	-	Trend smoother window size (must be odd).
low_pass	int \| None	None	Low-pass filter window size for seasonal component (must be odd if provided). Defaults to None (no low-pass filtering).
seasonal_deg	int	0	Polynomial degree for seasonal LOESS (0=constant, 1=linear).
trend_deg	int	1	Polynomial degree for trend LOESS (0=constant, 1=linear).
seasonal_jump	int	1	Jump (stride) for seasonal LOESS anchors to speed computation.
trend_jump	int	1	Jump (stride) for trend LOESS anchors to speed computation.
inner	int	1	Number of inner loop iterations for refinement.

Returns: tuple[jnp.ndarray, jnp.ndarray, jnp.ndarray] A tuple containing: - seas_est (jnp.ndarray): Seasonal component, shape (n,). - trend_est (jnp.ndarray): Trend component, shape (n,). - remainder (jnp.ndarray): Remainder (residual) component, shape (n,).