LogTransformer

yohou.stationarity.transformers.LogTransformer

Bases: BoxCoxTransformer

Logarithmic time series transformer.

Applies \(y = \ln(x + \text{offset})\), equivalent to BoxCoxTransformer with lmbda=0.

Parameters

Name	Type	Description	Default
offset	float >= 0.0	Offset to apply to the input time series before the log transform.	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 LogTransformer
>>> X = pl.DataFrame({
...     "time": [datetime(2024, 1, i) for i in range(1, 6)],
...     "value": [1.0, 4.0, 9.0, 16.0, 25.0],
... })
>>> transformer = LogTransformer(offset=0.0)
>>> transformer.fit(X)
LogTransformer(...)
>>> X_t = transformer.transform(X)
>>> "time" in X_t.columns
True

References

[1] Box, G.E.P., & Cox, D.R. (1964). "An analysis of transformations." Journal of the Royal Statistical Society: Series B, 26(2), 211-252.

See Also

• BoxCoxTransformer : Generalized power transform (parent class).
• ASinhTransformer : Variance stabilization for data with negatives.
• SeasonalLogDifferencing : Combined log + seasonal differencing.

Source Code

View on GitHub

Show/Hide source

class LogTransformer(BoxCoxTransformer):
    r"""Logarithmic time series transformer.

    Applies $y = \ln(x + \text{offset})$, equivalent to ``BoxCoxTransformer``
    with ``lmbda=0``.

    Parameters
    ----------
    offset : float >= 0.0, default=0.0
        Offset to apply to the input time series before the log transform.

    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 LogTransformer
    >>> X = pl.DataFrame({
    ...     "time": [datetime(2024, 1, i) for i in range(1, 6)],
    ...     "value": [1.0, 4.0, 9.0, 16.0, 25.0],
    ... })
    >>> transformer = LogTransformer(offset=0.0)
    >>> transformer.fit(X)  # doctest: +ELLIPSIS
    LogTransformer(...)
    >>> X_t = transformer.transform(X)
    >>> "time" in X_t.columns
    True

    References
    ----------
    [1] Box, G.E.P., & Cox, D.R. (1964). "An analysis of
        transformations." Journal of the Royal Statistical Society:
        Series B, 26(2), 211-252.

    See Also
    --------
    - [`BoxCoxTransformer`][yohou.stationarity.transformers.BoxCoxTransformer] : Generalized power transform (parent class).
    - [`ASinhTransformer`][yohou.stationarity.transformers.ASinhTransformer] : Variance stabilization for data with negatives.
    - [`SeasonalLogDifferencing`][yohou.stationarity.transformers.SeasonalLogDifferencing] : Combined log + seasonal differencing.

    """

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

    def __init__(self, offset: StrictFloat = 0.0):
        super().__init__(lmbda=0.0, 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"log_off_{self.offset}") for col in input_features]

        return feature_names

Methods

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"log_off_{self.offset}") for col in input_features]

    return feature_names

Tutorials

The following example notebooks use this component:

• Decomposition

  ---

  Data-Features

  Chain PolynomialTrendForecaster, PatternSeasonalityForecaster, and FourierSeasonalityForecaster inside DecompositionPipeline with component visualisation.

  View · Open in marimo

• 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

• How to Choose a Decomposition Strategy

  ---

  Forecasting-Models

  Build 2- and 3-component DecompositionPipeline forecasters chaining trend, seasonality, and residual models with target pre-transformation.

  View · Open in marimo

• Reduction Forecasting Walkthrough

  ---

  Getting-Started

  Walk through the full fit/predict/evaluate cycle with PointReductionForecaster, cross-validation, and grid search on a real dataset.

  View · Open in marimo

• Quickstart

  ---

  Quickstart

  Comprehensive end-to-end tour of yohou beyond the Getting Started tutorials, covering data loading, baseline forecasting, preprocessing pipelines, decomposition, cross-validation search, and interval prediction.

  View · Open in marimo