compose_weights

yohou.utils.weighting.compose_weights(*weight_fns)

Compose multiple weight functions by multiplication.

Creates a callable that applies multiple weight functions sequentially and multiplies the results. Useful for combining different weighting strategies (e.g., exponential decay + seasonal emphasis).

Parameters

Name	Type	Description	Default
*weight_fns	Callable[[Series], Series]	One or more weight functions to compose. Each must accept a time series and return a weight series.	()

Returns

Type	Description
Callable[[Series], Series]	Composed function that multiplies weights from all input functions.

See Also

• exponential_decay_weight : Exponential decay weights for recent times.
• linear_decay_weight : Linear decay weights for recent times.
• seasonal_emphasis_weight : Weights emphasizing seasonal positions.
• validate_callable_signature : Validate callable signature for time weighting.
• BaseReductionForecaster : Reduction forecaster supporting time_weight.

Examples

>>> import polars as pl
>>> from datetime import datetime
>>> times = pl.Series(
...     "time",
...     [
...         datetime(2024, 1, 1),
...         datetime(2024, 1, 2),
...         datetime(2024, 1, 3),
...     ],
... )
>>> # Combine exponential decay with seasonal emphasis
>>> weight_fn = compose_weights(
...     exponential_decay_weight(half_life=2), seasonal_emphasis_weight(seasonality=2, emphasis=1.5)
... )
>>> weights = weight_fn(times)

Source Code

View on GitHub

Show/Hide source

def compose_weights(
    *weight_fns: Callable[[pl.Series], pl.Series],
) -> Callable[[pl.Series], pl.Series]:
    """Compose multiple weight functions by multiplication.

    Creates a callable that applies multiple weight functions sequentially
    and multiplies the results. Useful for combining different weighting
    strategies (e.g., exponential decay + seasonal emphasis).

    Parameters
    ----------
    *weight_fns : Callable[[pl.Series], pl.Series]
        One or more weight functions to compose. Each must accept a time
        series and return a weight series.

    Returns
    -------
    Callable[[pl.Series], pl.Series]
        Composed function that multiplies weights from all input functions.

    See Also
    --------
    - [`exponential_decay_weight`][yohou.utils.weighting.exponential_decay_weight] : Exponential decay weights for recent times.
    - [`linear_decay_weight`][yohou.utils.weighting.linear_decay_weight] : Linear decay weights for recent times.
    - [`seasonal_emphasis_weight`][yohou.utils.weighting.seasonal_emphasis_weight] : Weights emphasizing seasonal positions.
    - [`validate_callable_signature`][yohou.utils.weighting.validate_callable_signature] : Validate callable signature for time weighting.
    - [`BaseReductionForecaster`][yohou.base.reduction.BaseReductionForecaster] : Reduction forecaster supporting time_weight.

    Examples
    --------
    >>> import polars as pl
    >>> from datetime import datetime
    >>> times = pl.Series(
    ...     "time",
    ...     [
    ...         datetime(2024, 1, 1),
    ...         datetime(2024, 1, 2),
    ...         datetime(2024, 1, 3),
    ...     ],
    ... )
    >>> # Combine exponential decay with seasonal emphasis
    >>> weight_fn = compose_weights(
    ...     exponential_decay_weight(half_life=2), seasonal_emphasis_weight(seasonality=2, emphasis=1.5)
    ... )
    >>> weights = weight_fn(times)

    """
    if not weight_fns:
        raise ValueError("At least one weight function must be provided")

    def _weight_fn(time: pl.Series) -> pl.Series:
        """Apply composed weighting to time series.

        Parameters
        ----------
        time : pl.Series
            Time series (datetime type).

        Returns
        -------
        pl.Series
            Weight series from multiplying all component weight functions.

        """
        # Start with uniform weights
        result = pl.Series(np.ones(len(time)), dtype=pl.Float64)

        # Multiply by each weight function
        for fn in weight_fns:
            result = result * fn(time)

        return result.alias("weight")

    return _weight_fn

Tutorials

The following example notebooks use this component:

• How to Apply Time-Weighted Training

  ---

  Forecasting-Models

  Use time_weight and sample_weight_alignment to emphasise recent or seasonal training samples in PointReductionForecaster, with visualisation of weight curves and alignment strategy comparison.

  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