fusionlab.utils.ts_utils.get_decomposition_method

fusionlab.utils.ts_utils.get_decomposition_method(df, value_col, dt_col=None, max_period=24, method='auto', min_period=2, verbose=0)[source]

Infer the suitable decomposition method for a given time series, based on certain heuristics or user preferences. This function helps decide whether to apply an additive or multiplicative model, and what seasonal period to use for subsequent decomposition steps.

\[Y_t = T_t + S_t + \epsilon_t, \quad \text{(Additive Model)}\]
\[\log(Y_t) = \log(T_t) + \log(S_t) + \epsilon_t, \quad \text{(Multiplicative Model)}\]

Here, \(T_t\) is the trend component, \(S_t\) the seasonal component, and \(\epsilon_t\) the irregular (residual) component [1].

Parameters:

  • df (pandas.DataFrame) – The DataFrame containing time series data. Must include the target variable in <value_col> and optionally a datetime column <dt_col>.

  • value_col (str) – The column name of the target time series variable to decompose.

  • dt_col (str, optional) – The column name representing datetime. If None, the index of df is assumed to be the time dimension.

  • max_period (int, optional) – The maximum seasonal period to check. If method='auto', the function may inspect data for possible seasonality up to this limit.

  • method ({'auto','additive','multiplicative'}, optional) – The approach for decomposition. If 'auto', the function tries to detect whether data is strictly positive (favoring multiplicative) or can be well-modeled additively. If 'additive' or 'multiplicative', uses that model directly.

  • min_period (int, optional) – The minimum seasonal period to consider. For instance, setting it to 2 prevents using a period of 1 (no real seasonality).

  • verbose (int, optional) –

    The level of logging:

    • 0: No output.

    • 1: Basic info messages.

    • 2: More diagnostic details.

Returns:

  • best_method (str) – The inferred model type: 'additive' or 'multiplicative'.

  • best_period (int) – The inferred seasonal period. If the data shows minimal seasonality or the detection fails, returns a default value of 1 or a recognized fallback.

Notes

Choosing between additive and multiplicative models can hinge on data behavior. If the time series is strictly positive and exhibits increasing variance with time, a multiplicative approach is often more suitable [2]. When seasonality does not scale with level, an additive approach may suffice.

Examples

>>> import pandas as pd
>>> from fusionlab.utils.ts_utils import get_decomposition_method
>>> data = {
...     'Date': [
...         '2020-01-01','2020-02-01','2020-03-01',
...         '2020-04-01','2020-05-01'
...     ],
...     'Sales': [100, 120, 140, 135, 150]
... }
>>> df = pd.DataFrame(data)
>>> df['Date'] = pd.to_datetime(df['Date'])
>>> df.set_index('Date', inplace=True)
>>> mtype, speriod = get_decomposition_method(
...     df,
...     value_col='Sales',
...     method='auto',
...     verbose=1
... )
Detected model type: additive
Detected seasonal period: 1

See also

seasonal_decompose

Decompose a time series into trend, seasonal, and residual components.

trend_analysis

Detect stationarity and linear trend in time series data.

References