MSTL

MSTL

class MSTL(*, periods: int | Sequence[int] | None = None, windows: int | Sequence[int] | None = None, lmbda: float | str | None = None, iterate: int | None = 2, stl_kwargs: dict[str, int | bool | None] | None = None, return_components: bool = False)[source]

Season-Trend decomposition using LOESS for multiple seasonalities.

Direct interface for statsmodels.tsa.seasonal.MSTL for transform, with sktime native extensions to allow use in forecasting pipelines.

MSTL can be used to perform deseasonalization or decomposition:

fit stores the decomposed values in self.trend_, self.seasonal_, and self.resid_.

If return_components=False, then transform returns a pd.Series of the deseasonalized values, i.e., trend plus residual component. The individual seasonal and residual components can be found in self.trend_ and self.resid_.

If return_components=True, then transform returns a full components decomposition, in a DataFrame with cols (for each input column), in this order:

• “trend” - the trend component

• “resid” - the residuals after de-trending, de-seasonalizing

• “seasonal” - a single sum-of-seasonalities component, if periods is None.

• “seasonal_<period>” - the seasonal component(s), where <period> is an integer indicating the periodicity, one such component per element in periods, if periods is an array-like of integers.

MSTL performs inverse_transform by reconstituting the signal from its components, and can be used for pipelining in a TransformedTargetForecaster, see examples below.

• if periods are provided, the transformation will deseasonalize, and reseasonalize after forecast.

• if periods are not provided, and return_components=False, the forecast will be a pure trend forecast, using sum of trend and residual components.

• if return_components=True, the forecaster has access to all components, and can apply different forecasters to different components.

See the examples below for usage.

For automated detection of seasonalities using a custom seasonality detection algorithm, pipeline MSTL with the respective estimator, e.g., SeasonalityACF.

Parameters:

endogarray_like

Data to be decomposed. Must be squeezable to 1-d.

periods{int, array_like, None}, optional

Periodicity of the seasonal components. If None and endog is a pandas Series or DataFrame, attempts to determine from endog. If endog is a ndarray, periods must be provided.

windows{int, array_like, None}, optional

Length of the seasonal smoothers for each corresponding period. Must be an odd integer, and should normally be >= 7 (default). If None then default values determined using 7 + 4 * np.arange(1, n + 1, 1) where n is number of seasonal components.

lmbda{float, str, None}, optional

The lambda parameter for the Box-Cox transform to be applied to endog prior to decomposition. If None, no transform is applied. If auto, a value will be estimated that maximizes the log-likelihood function.

iterateint, optional

Number of iterations to use to refine the seasonal component.

stl_kwargsdict, optional

Arguments to pass to STL.

return_componentsbool, default=False

• if False, will return only the MSTL transformed series, same as trend plus residual component. The resulting series has the same number of columns as the input.

• if True, will return all components of the decomposition,

  a multivariate series with DataFrame cols (for each input column):

  • “trend” - the trend component

  • “resid” - the residuals after de-trending, de-seasonalizing

  • “seasonal” - a single sum-of-seasonalities component, if

  periods is None. * “seasonal_<period>” - the seasonal component(s),

  where <period> is an integer indicating the periodicity, one such component per element in periods

  All components together sum up to the original series, in-sample.

Attributes:

trend_pd.Series

Trend component of series seen in fit.

resid_pd.Series

Residuals component of series seen in fit.

seasonal_pd.DataFrame

If periods is None, this contains a single column, with the sum of all seasonal components of the X seen in fit. If periods is an array-like of integers, this consists of multiple columns seasonal_<period>, each corresponding to a seasonal component of the series.

References

[1] https://www.statsmodels.org/dev/generated/statsmodels.tsa.seasonal.MSTL.html

Examples

Simple use case: decompose a time series into trend, seasonal, residual components >>> import matplotlib.pyplot as plt # doctest: +SKIP >>> from sktime.datasets import load_airline >>> from sktime.transformations.detrend import MSTL >>> X = load_airline() >>> X.index = X.index.to_timestamp() >>> mstl = MSTL(return_components=True) >>> mstl.fit(X) MSTL(…) >>> res = mstl.transform(X) >>> res.plot() # doctest: +SKIP >>> plt.tight_layout() # doctest: +SKIP >>> plt.show() # doctest: +SKIP

MSTL can be pipelined with a forecaster for multiple deseasonalized forecasts. The following example uses a simple trend forecaster, applied to a series deseasonalized with MSTL at periods 2 and 12. After the trend forecast, the seasonal components are added back to the forecast automatically. >>> from sktime.datasets import load_airline >>> from sktime.transformations.detrend import MSTL >>> from sktime.forecasting.trend import TrendForecaster >>> >>> mstl_trafo = MSTL(periods=[2, 12]) >>> mstl_deseason_fcst = mstl_trafo * TrendForecaster() >>> y = load_airline() >>> mstl_deseason_fcst.fit(y, fh=[1, 2, 3]) TransformedTargetForecaster(…) >>> y_pred = mstl_deseason_fcst.predict()

MSTL can also be used to make forecasts using the full component decomposition. For this, set return_components=True when pipelining. The forecaster in the pipeline will then be given a multivariate series with the components as columns, i.e., “trend”, “resid”, “seasonal_2”, “seasonal_12”. To apply different forecasters to different components, use a ColumnEnsembleForecaster; to apply the same forecaster to all components, simply pipeline with the forecaster. The following example uses a TrendForecaster for the trend, a seasonal naive forecaster for the seasonal components, with different seasonalities, and a naive forecaster for the residuals. >>> from sktime.datasets import load_airline >>> from sktime.transformations.detrend import MSTL >>> from sktime.forecasting.compose import ColumnEnsembleForecaster >>> from sktime.forecasting.naive import NaiveForecaster >>> from sktime.forecasting.trend import TrendForecaster >>> >>> mstl_trafo_comp = MSTL(periods=[2, 12], return_components=True) >>> mstl_component_fcst = mstl_trafo_comp * ColumnEnsembleForecaster( … [ … (“trend”, TrendForecaster(), “trend”), … (“sp2”, NaiveForecaster(strategy=”last”, sp=2), “seasonal_2”), … (“sp12”, NaiveForecaster(strategy=”last”, sp=12), “seasonal_12”), … (“residual”, NaiveForecaster(strategy=”last”), “resid”), … ] … ) >>> y = load_airline() >>> mstl_component_fcst.fit(y, fh=[1, 2, 3]) TransformedTargetForecaster(…) >>> y_pred = mstl_component_fcst.predict()

Methods

check_is_fitted([method_name])	Check if the estimator has been fitted.
clone()	Obtain a clone of the object with same hyper-parameters and config.
clone_tags(estimator[, tag_names])	Clone tags from another object as dynamic override.
create_test_instance([parameter_set])	Construct an instance of the class, using first test parameter set.
create_test_instances_and_names([parameter_set])	Create list of all test instances and a list of names for them.
fit(X[, y])	Fit transformer to X, optionally to y.
fit_transform(X[, y])	Fit to data, then transform it.
get_class_tag(tag_name[, tag_value_default])	Get class tag value from class, with tag level inheritance from parents.
get_class_tags()	Get class tags from class, with tag level inheritance from parent classes.
get_config()	Get config flags for self.
get_fitted_params([deep])	Get fitted parameters.
get_param_defaults()	Get object's parameter defaults.
get_param_names([sort])	Get object's parameter names.
get_params([deep])	Get a dict of parameters values for this object.
get_tag(tag_name[, tag_value_default, ...])	Get tag value from instance, with tag level inheritance and overrides.
get_tags()	Get tags from instance, with tag level inheritance and overrides.
get_test_params([parameter_set])	Return testing parameter settings for the estimator.
inverse_transform(X[, y])	Inverse transform X and return an inverse transformed version.
is_composite()	Check if the object is composed of other BaseObjects.
load_from_path(serial)	Load object from file location.
load_from_serial(serial)	Load object from serialized memory container.
reset()	Reset the object to a clean post-init state.
save([path, serialization_format])	Save serialized self to bytes-like object or to (.zip) file.
set_config(**config_dict)	Set config flags to given values.
set_params(**params)	Set the parameters of this object.
set_random_state([random_state, deep, ...])	Set random_state pseudo-random seed parameters for self.
set_tags(**tag_dict)	Set instance level tag overrides to given values.
transform(X[, y])	Transform X and return a transformed version.
update(X[, y, update_params])	Update transformer with X, optionally y.