Lag transforms

The mlforecast.lag_transforms module provides built-in lag transformations: statistics computed over lagged values of the target that are used as features by the forecasting model. You pass them to MLForecast through the lag_transforms argument, a dict whose keys are the lags to apply the transformation to and whose values are lists of transformation instances.

from mlforecast import MLForecast
from mlforecast.lag_transforms import ExpandingStd, RollingMean

fcst = MLForecast(
    models=[...],
    freq='D',
    lag_transforms={
        1: [ExpandingStd()],
        7: [RollingMean(window_size=7), RollingMean(window_size=28)],
    },
)

The transforms fall into four families, each with several variants:

Rolling — RollingMean, RollingStd, RollingMin, RollingMax, RollingQuantile: fixed-window statistics over the lagged target.
Seasonal rolling — SeasonalRollingMean, SeasonalRollingStd, SeasonalRollingMin, SeasonalRollingMax, SeasonalRollingQuantile: rolling statistics computed across same-position observations in successive seasons (e.g. last 4 Mondays).
Expanding — ExpandingMean, ExpandingStd, ExpandingMin, ExpandingMax, ExpandingQuantile: statistics over all observations up to the lag.
Exponentially weighted — ExponentiallyWeightedMean: a weighted mean that emphasises recent observations.

Two combinators let you build richer features from these primitives: Offset applies a transformation at a shifted lag, and Combine joins two transformations with a binary operator (for example a ratio of two rolling means at different windows). The basic usage is per-series — each transformation is computed independently for every series. The next section describes how to instead compute these statistics across multiple series at once. For a worked walkthrough of all of the above, including the Combine / Offset combinators and how to plug in custom numba-based transforms, see the Lag transformations how-to guide.

Pooled mode: `global_`, `groupby`, and `partition_by`

Every built-in rolling, expanding, seasonal-rolling, and exponentially weighted transform accepts three pooling parameters that let you compute the statistic across multiple series at once:

global_: bool — when True, the statistic is computed across all series aggregated by timestamp. Every series receives the same feature value at each timestamp.
groupby: Sequence[str] — column names to group by before computing the statistic. Columns must be declared as static features when calling fit / preprocess. Series in the same group share the feature value at each timestamp; series in different groups get different values.
partition_by: Sequence[str] — column names to partition further along a dynamic (time-varying) key, such as promo or regime. Each unique combination of partition values gets its own bucket. Composes with global_ (cross-series aggregates within each partition), with groupby (group aggregates within each partition), or stands alone (per-(id, partition) buckets — local mode). Partition columns must be supplied via X_df at prediction.

global_ and groupby are mutually exclusive on the same transform. partition_by composes with either one or stands alone. All pooled modes require every series to end at the same timestamp, including local partition_by. RANGE semantics. Pooled transforms use SQL-style RANGE BETWEEN ... PRECEDING windows over actual timestamps, not row positions. Series with staggered starts simply do not contribute to the window until they have observations — no synthetic zeros are injected. Pooled mode assumes a continuous, gap-free time grid within each series; combining validate_data=False with a pooled transform raises a UserWarning. For partition_by, ordinals come from the parent calendar (global or group scope for nonlocal modes, per-id for local mode), so a partition bucket with gaps still preserves RANGE window semantics across those gaps rather than collapsing to row-based behavior. min_samples divergence. In local (per-series) mode, min_samples is capped at window_size by coreforecast. In pooled mode, min_samples counts total non-NaN observations across all series in the bucket within the rolling window, with no capping. This makes it useful as a coverage threshold: RollingMean(window_size=1, min_samples=2, groupby=["brand"]) produces a non-null value only at timestamps where at least two series in the brand contribute observations. See the Pooled lag transforms how-to guide for end-to-end examples.

`RollingQuantile`

RollingQuantile(p, window_size, min_samples=None, global_=False, groupby=None, partition_by=None, time_agg=None, **kwargs)

Bases: _RollingBase Rolling quantile.

`RollingMax`

Bases: _RollingBase Rolling statistic

`RollingMin`

Bases: _RollingBase Rolling statistic

`RollingStd`

Bases: _RollingBase Rolling statistic