fusionlab.utils.ts_utils.transform_stationarity¶

fusionlab.utils.ts_utils.transform_stationarity(df, dt_col=None, value_col=None, method='differencing', order=1, seasonal_period=None, detrend_method='linear', view=True, fig_size=(12, 6), show_grid=True, drop_original=True, reset_index=False, verbose=0)[source]¶

Perform stationarity transformations on a time series dataset by applying differencing, variance stabilization, or detrending. This function helps reduce non-stationary components (trends, seasonal effects) to align the data with time-series modeling assumptions [1].

\[\Delta^d (X_t) = X_t - X_{t-d},\]

for differencing, and

\[Y_t = \log(X_t),\]

for a logarithmic transform.

Parameters:

df (pandas.DataFrame) – The input DataFrame containing time series data. The index or a column should correspond to time.
dt_col (str, optional) – Column name representing the datetime dimension (e.g., “Date”). If None, the function assumes the index is already datetime-like.
value_col (str, optional) – Name of the target variable column (e.g., “Sales”). This column is transformed to promote stationarity.
method ({'differencing', 'log', 'sqrt', 'detrending'}, optional) –
The transformation method:
- 'differencing': Remove trends or cycles by subtracting lagged values.
- 'log': Apply a log transform for variance stabilization (positive values only).
- 'sqrt': Apply a square-root transform (non-negative values only).
- 'detrending': Remove trend either by linear regression or STL decomposition.
order (int, optional) – Order of differencing if method='differencing'. For example, 1 for first differencing, 2 for second differencing, etc.
seasonal_period (int, optional) – Seasonal period for seasonal differencing or STL decomposition. For instance, 12 in monthly data with annual seasonality.
detrend_method ({'linear', 'stl'}, optional) –
Method for detrending if method='detrending':
- 'linear': Fit a linear regression to the series and subtract the fitted line.
- 'stl': Use STL (Seasonal and Trend decomposition) to remove the estimated trend component.
view (bool, optional) – If True, displays plots of original and transformed data in a 2-row subplot.
fig_size (tuple of (float, float), optional) – The figure width and height in inches for the optional plots. Default is (12, 6).
show_grid (bool, optional) – Whether to show gridlines in the plots. Default True.
drop_original (bool, optional) – Whether to keep the original column in the returned DataFrame. If True, only the transformed column is kept (besides other unrelated columns).
reset_index (bool, optional) – If True, resets the DataFrame index before returning.
verbose (int, optional) –
Verbosity level:
- 0 : No output
- 1 : Basic info about transformations
- 2+ : More detailed logs (not fully implemented here).

Returns:

transformed_df – A DataFrame containing the transformed series in a new column named '<value_col>_transformed'. If drop_original=False, it also includes the original series in column '<value_col>'.

Return type:

pandas.DataFrame

Notes

Stationarity transformations aim to remove or lessen trends and periodic components, aligning data with the assumptions of many time-series models such as ARIMA [2]. Log and square-root transforms assume positive values, so care must be taken with zero or negative data.

Examples

>>> import pandas as pd
>>> from fusionlab.utils.ts_utils import transform_stationarity
>>> data = {
...     'Date': [
...         '2021-01-01', '2021-01-02', '2021-01-03',
...         '2021-01-04', '2021-01-05'
...     ],
...     'Sales': [10, 12, 14, 13, 15]
... }
>>> df = pd.DataFrame(data)
>>> df['Date'] = pd.to_datetime(df['Date'])
>>> df.set_index('Date', inplace=True)
>>> # Perform first-order differencing and plot
>>> df_trans = transform_stationarity(
...     df,
...     value_col='Sales',
...     method='differencing',
...     order=1,
...     view=True,
...     verbose=1
... )
Target variable: Sales
Datetime column: Date
Transformation method: differencing
Applying first-order differencing with order=1.