BaseWeighter¶

class BaseWeighter(BaseEstimator, metaclass=abc.ABCMeta):
    """Base class for time-axis weighter estimators.

    A weighter maps a *key* series (datetime times, vintage times, or integer
    forecasting steps) to a series of non-negative weights. Concrete subclasses
    declare their tunable parameters in ``_parameter_constraints`` and implement
    :meth:`compute_weights`. Because weighters are scikit-learn estimators, their
    parameters can be addressed with the ``__`` syntax (e.g.
    ``time_weighter__half_life``) and tuned by search.

    Notes
    -----
    Weighters are stateless by default: :meth:`fit` is a no-op that exists so a
    future data-dependent weighter can hook into the host estimator's ``fit``
    without an API change.

    See Also
    --------
    - [`ExponentialDecayWeighter`][yohou.weighting.weighters.ExponentialDecayWeighter] : Recency decay weighting.
    - [`LinearDecayWeighter`][yohou.weighting.weighters.LinearDecayWeighter] : Linear recency weighting.
    - [`SeasonalEmphasisWeighter`][yohou.weighting.weighters.SeasonalEmphasisWeighter] : Seasonal emphasis weighting.
    - [`LookupWeighter`][yohou.weighting.weighters.LookupWeighter] : Explicit per-key weights.
    - [`TableWeighter`][yohou.weighting.weighters.TableWeighter] : DataFrame-driven weights.
    - [`CompositeWeighter`][yohou.weighting.weighters.CompositeWeighter] : Combine weighters by product or mean.

    """

    _parameter_constraints: dict = {}

    def __init_subclass__(cls, **kwargs: Any) -> None:
        """Merge parameter constraints from all classes in the MRO."""
        super().__init_subclass__(**kwargs)
        merged: dict = {}
        for klass in reversed(cls.__mro__):
            own = klass.__dict__.get("_parameter_constraints")
            if own and isinstance(own, dict):
                merged.update(own)
        cls._parameter_constraints = merged

    def fit(self, y: pl.DataFrame | None = None, **params: Any) -> BaseWeighter:
        """Fit the weighter (no-op by default).

        Parameters
        ----------
        y : pl.DataFrame or None, default=None
            Training data. Ignored by stateless weighters.
        **params : dict
            Ignored. Present for routing compatibility.

        Returns
        -------
        self

        """
        return self

    @abc.abstractmethod
    def compute_weights(self, key: pl.Series, group_name: str | None = None) -> pl.Series:
        """Compute one weight per element of ``key``.

        Parameters
        ----------
        key : pl.Series
            Key series to weight: datetime times, vintage times, or integer
            forecasting steps.
        group_name : str or None, default=None
            Panel group name for panel-aware weighting, or None for global data.

        Returns
        -------
        pl.Series
            Float64 weight series aligned to ``key`` (alias ``"weight"``).

        """
        raise NotImplementedError