AbsoluteSeasonalReturn¶

class AbsoluteSeasonalReturn(SeasonalDifferencing):
    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

    Notes
    -----
    This transformer is stateful with ``observation_horizon = seasonality``.
    The first ``seasonality`` rows are dropped in the output. Inverse
    transform requires the ``X_p`` prior-context argument.

    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

    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}") for col in input_features]

        return feature_names