AbsoluteSeasonalReturn

yohou.stationarity.transformers.AbsoluteSeasonalReturn

Bases: BaseTransformer

Absolute seasonal return (difference) time series transformer.

Computes the absolute difference relative to the value from seasonality time steps ago:

\[\Delta_s X_t = X_t - X_{t-s}\]

This is semantically similar to SeasonalDifferencing but provides a consistent API with SeasonalReturn and explicitly handles the offset parameter for API symmetry.

Parameters

Name	Type	Description	Default
seasonality	int > 1	Seasonality lag for computing differences.	1
offset	float >= 0.0	Offset parameter (provided for API consistency with SeasonalReturn, but note that offset cancels out in the computation).	0.0

Attributes

Name	Type	Description
n_features_in_	int	Number of features seen during fit.
feature_names_in_	list of str	Names of features seen during fit (excluding "time" column).

Examples

>>> import polars as pl
>>> from datetime import datetime
>>> from yohou.stationarity import AbsoluteSeasonalReturn
>>> X = pl.DataFrame({
...     "time": [datetime(2024, 1, i) for i in range(1, 6)],
...     "value": [100.0, 110.0, 105.0, 115.0, 120.0],
... })
>>> transformer = AbsoluteSeasonalReturn(seasonality=2, offset=0.0)
>>> transformer.fit(X)
AbsoluteSeasonalReturn(...)
>>> X_t = transformer.transform(X)
>>> len(X_t) == len(X) - 2  # First 2 rows dropped
True

References

[1] Hyndman, R.J., & Athanasopoulos, G. (2021). "Forecasting: principles and practice," 3^rd edition, OTexts: Melbourne, Australia. OTexts.com/fpp3. Chapter 9.1.

See Also

• SeasonalReturn : Percentage returns instead of absolute differences.
• SeasonalDifferencing : Equivalent computation with different API.

Source Code

View on GitHub

Show/Hide source

class AbsoluteSeasonalReturn(BaseTransformer):
    r"""Absolute seasonal return (difference) time series transformer.

    Computes the absolute difference relative to the value from ``seasonality``
    time steps ago:

    $$\Delta_s X_t = X_t - X_{t-s}$$

    This is semantically similar to ``SeasonalDifferencing`` but provides a
    consistent API with ``SeasonalReturn`` and explicitly handles the offset
    parameter for API symmetry.

    Parameters
    ----------
    seasonality : int > 1, default=1
        Seasonality lag for computing differences.

    offset : float >= 0.0, default=0.0
        Offset parameter (provided for API consistency with SeasonalReturn,
        but note that offset cancels out in the computation).

    Attributes
    ----------
    n_features_in_ : int
        Number of features seen during fit.
    feature_names_in_ : list of str
        Names of features seen during fit (excluding "time" column).

    Examples
    --------
    >>> import polars as pl
    >>> from datetime import datetime
    >>> from yohou.stationarity import AbsoluteSeasonalReturn
    >>> X = pl.DataFrame({
    ...     "time": [datetime(2024, 1, i) for i in range(1, 6)],
    ...     "value": [100.0, 110.0, 105.0, 115.0, 120.0],
    ... })
    >>> transformer = AbsoluteSeasonalReturn(seasonality=2, offset=0.0)
    >>> transformer.fit(X)  # doctest: +ELLIPSIS
    AbsoluteSeasonalReturn(...)
    >>> X_t = transformer.transform(X)
    >>> len(X_t) == len(X) - 2  # First 2 rows dropped
    True

    References
    ----------
    [1] Hyndman, R.J., & Athanasopoulos, G. (2021). "Forecasting:
        principles and practice," 3rd edition, OTexts: Melbourne, Australia.
        OTexts.com/fpp3. Chapter 9.1.

    See Also
    --------
    - [`SeasonalReturn`][yohou.stationarity.transformers.SeasonalReturn] : Percentage returns instead of absolute differences.
    - [`SeasonalDifferencing`][yohou.stationarity.transformers.SeasonalDifferencing] : Equivalent computation with different API.

    """

    _parameter_constraints: dict = {
        "seasonality": [Interval(numbers.Integral, 1, None, closed="left")],
        "offset": [Interval(numbers.Real, 0, None, closed="left")],
    }

    _tags = {"stateful": True, "invertible": True}

    def __init__(self, seasonality: StrictInt = 1, offset: StrictFloat = 0.0):
        self.seasonality = seasonality
        self.offset = offset

    @property
    def observation_horizon(self) -> int:  # noqa: D102
        """Return the number of past observations needed."""
        return self.seasonality

    def _transform(self, X: pl.DataFrame) -> pl.DataFrame:
        """Transform the input time series."""
        time = X.select(cs.by_name("time"))[self.seasonality :]

        # Compute absolute difference: X_t - X_{t-seasonality}
        # Note: offset cancels out in addition/subtraction
        X_t = X.select(~cs.by_name("time")).select(pl.all().diff(self.seasonality))[self.seasonality :]

        feature_names = self.get_feature_names_out()
        X_t = X_t.rename(dict(zip(X_t.columns, feature_names, strict=False)))
        X_t = pl.concat([time, X_t], how="horizontal")

        return X_t

    def _inverse_transform(self, X_t: pl.DataFrame, X_p: pl.DataFrame | None = None) -> pl.DataFrame:
        """Inverse-transform the time series."""
        X_t, X_p = validate_transformer_data(
            self,
            X=X_t,
            reset=False,
            inverse=True,
            X_p=X_p,
            observation_horizon=self.observation_horizon,
            stateful=True,
        )

        time = X_t.select(cs.by_name("time"))
        X_t.columns = X_p.columns
        X = pl.concat([X_p, X_t])

        # Get the columns and their dtypes (excluding "time")
        X_no_time = X.select(~cs.by_name("time"))
        cols_and_dtypes = list(zip(X_no_time.columns, X_no_time.dtypes, strict=False))

        def inverse_diff_col(series: pl.Series) -> pl.Series:
            """Reverse seasonal differencing for a single series."""
            arr = series.to_numpy().copy()
            for i in range(len(X_p), len(arr)):
                arr[i] += arr[i - self.seasonality]
            return pl.Series(arr)

        X = X_no_time.with_columns([
            pl.col(col).map_batches(inverse_diff_col, return_dtype=dtype) for col, dtype in cols_and_dtypes
        ])[len(X_p) :]
        X.columns = self.feature_names_in_
        X = pl.concat([time, X], how="horizontal")

        return X

    def get_feature_names_out(self, input_features: list[str] | None = None) -> list[str]:
        """Get output feature names for transformation.

        Parameters
        ----------
        input_features : array-like of str or None, default=None
            Column names of the input features.  If ``None``, uses the
            feature names seen during ``fit``.

        Returns
        -------
        list of str
            Output feature names after transformation.

        """
        input_features = _check_feature_names_in(self, input_features)
        feature_names = [
            panel_aware_prefix(col, f"abs_return_s_{self.seasonality}_off_{self.offset}") for col in input_features
        ]

        return feature_names

Methods

observation_horizon property

Return the number of past observations needed.

get_feature_names_out(input_features=None)

Get output feature names for transformation.

Parameters

Name	Type	Description	Default
input_features	array-like of str or None	Column names of the input features. If None, uses the feature names seen during fit.	None

Returns

Type	Description
list of str	Output feature names after transformation.

Source Code

View on GitHub

Show/Hide source

def get_feature_names_out(self, input_features: list[str] | None = None) -> list[str]:
    """Get output feature names for transformation.

    Parameters
    ----------
    input_features : array-like of str or None, default=None
        Column names of the input features.  If ``None``, uses the
        feature names seen during ``fit``.

    Returns
    -------
    list of str
        Output feature names after transformation.

    """
    input_features = _check_feature_names_in(self, input_features)
    feature_names = [
        panel_aware_prefix(col, f"abs_return_s_{self.seasonality}_off_{self.offset}") for col in input_features
    ]

    return feature_names

Tutorials

The following example notebooks use this component:

• How to Apply Stationarity Transforms

  ---

  Data-Features

  Catalogue of variance-stabilising and detrending transforms: LogTransformer, BoxCox, SeasonalDifferencing, SeasonalReturn, and ASinh with inverse verification.

  View · Open in marimo