API Reference / algorithms / timeseries /

stl_decomposition.py

Seasonal-Trend decomposition using LOESS (STL) for time series.

Classes

STLDecomposition

class algorithms.timeseries.stl_decomposition.STLDecomposition(Regressor)

Seasonal-Trend decomposition using LOESS (STL) for time series decomposition.

STL is a robust decomposition method for time series that extracts trend, seasonal, and remainder components. It uses locally weighted regression (LOESS) for smoothing, which allows it to handle non-linear trends and changing seasonality.
Constructor 
__init__(
    self,
    period: int,
    seasonal: int = 7,
    trend: int | None = None,
    low_pass: int | None = None,
    seasonal_deg: int = 1,
    trend_deg: int = 1,
    low_pass_deg: int = 1,
    robust: bool = False,
    seasonal_jump: int = 1,
    trend_jump: int = 1,
)

Overview

The STL decomposition procedure works as follows:

  1. Detrend the series by subtracting the current trend estimate.
  2. Extract the seasonal component by smoothing cycle-subseries
(one subseries per seasonal period position) using LOESS.
  1. Apply a low-pass filter to the seasonal component.
  2. Deseasonalize the series by subtracting the seasonal component.
  3. Extract the trend by LOESS smoothing of the deseasonalized series.
  4. Repeat steps 1-5 (inner loop) to refine components.
  5. Optionally apply robustness weights (outer loop) to reduce the
influence of outliers, then re-run the inner loop.

Theory

The STL algorithm assumes an additive decomposition model:

Y_t = T_t + S_t + R_t
where:
  • Y_t: The observed time series value at time t.
  • T_t: The trend component, representing long-term progression.
  • S_t: The seasonal component, representing repeating patterns.
  • R_t: The remainder (residual) component, representing noise
or irregular variations.

The algorithm consists of two recursive loops:

  1. Inner Loop: Iteratively updates the trend and seasonal
components using LOESS smoothing and filtering.
  1. Outer Loop: Computes robustness weights to reduce the
impact of outliers in the subsequent inner loop iterations.

Parameters

period
int
The period of the seasonality (e.g., 12 for monthly data).
seasonal
int = 7
The length of the seasonal smoother window. Must be an odd integer.
trend
int = None
The length of the trend smoother window. Must be an odd integer. If None, a default value is calculated based on the period and seasonal parameters.
low_pass
int = None
The length of the low-pass filter window. Must be an odd integer.
seasonal_deg
{0, 1} = 1
The degree of locally-fitted polynomial for seasonal smoothing.
trend_deg
{0, 1} = 1
The degree of locally-fitted polynomial for trend smoothing.
low_pass_deg
{0, 1} = 1
The degree of locally-fitted polynomial for low-pass smoothing.
robust
bool = False
If True, use robust fitting with bisquare weights in the outer loop to reduce the influence of outliers.
seasonal_jump
int = 1
Linear interpolation step size for seasonal smoothing to increase computation speed.
trend_jump
int = 1
Linear interpolation step size for trend smoothing to increase computation speed.

Attributes

trend_
np.ndarray of shape (n_obs,)
The extracted trend component.
seasonal_
np.ndarray of shape (n_obs,)
The extracted seasonal component.
resid_
np.ndarray of shape (n_obs,)
The extracted remainder component.
weights_
np.ndarray of shape (n_obs,) or None
The robustness weights used during the fitting process (only available if robust=True).
n_obs_
int
The total number of observations in the input series.

Notes

Complexity:

  • Training: O(n \cdot k) where n is the number of
samples and k is the number of loop iterations.
  • Prediction: Not applicable (decomposition only).
When to use STLDecomposition:
  • Exploratory analysis of seasonal time series
  • When the seasonal pattern may change over time
  • Data with outliers requiring robust decomposition
  • As a preprocessing step before forecasting with other models
  • When you need separate trend, seasonal, and residual components

References

Cleveland1990
Cleveland, R. B., Cleveland, W. S., McRae, J. E., & Terpenning, I. (1990). STL: A seasonal-trend decomposition. Journal of Official Statistics, 6(1), 3-73.

See Also

ExponentialSmoothing

Holt-Winters method with built-in trend and seasonal decomposition.
Prophet

Additive decomposition model with trend changepoints and holiday effects.
ARIMA

Box-Jenkins forecasting after removing trend via differencing.
python 
>>> import numpy as np
>>> from tuiml.algorithms.timeseries import STLDecomposition
>>> t = np.linspace(0, 10, 100)
>>> y = 0.5 * t + np.sin(t) + np.random.normal(size=100)
>>> stl = STLDecomposition(period=10)
>>> stl.fit(y)
>>> trend, seasonal, resid = stl.trend_, stl.seasonal_, stl.resid_

Methods

get_parameter_schema (cls) -> Dict[str, Dict[str, Any]]

Return JSON Schema for algorithm parameters.

get_capabilities (cls) -> List[str]

Return supported capabilities.

get_complexity (cls) -> str

Return complexity analysis.

get_references (cls) -> List[str]

Return academic citations.

fit (self, y: np.ndarray, X: Optional[np.ndarray]=None) -> 'STLDecomposition'

Fit the STL decomposition to time series data.

Parameters
y
np.ndarray of shape (n_samples,)
Time series values to decompose.
X
np.ndarray = None
Ignored. Present for API consistency with estimators.
Returns
self
STLDecomposition
Fitted estimator.
predict (self, X: Optional[np.ndarray]=None) -> np.ndarray

Return the reconstructed series from trend and seasonal components.

Parameters
X
np.ndarray = None
Ignored.
Returns
reconstructed
np.ndarray of shape (n_obs,)
Reconstructed series :math:`T_t + S_t`.
fit_predict (self, y: np.ndarray, X: Optional[np.ndarray]=None) -> np.ndarray

Fit the decomposition and return the reconstructed series.

Parameters
y
np.ndarray of shape (n_samples,)
Time series values to fit.
X
np.ndarray = None
Ignored.
Returns
reconstructed
np.ndarray of shape (n_samples,)
Reconstructed series :math:`T_t + S_t`.
get_components (self) -> Dict[str, np.ndarray]

Get all decomposed components.

Returns
components
dict
Dictionary with keys 'trend', 'seasonal', 'resid'.