mlforecast

The mlforecast.lag_transforms module provides several families of transformations:

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

Combinators:

• Offset: Applies a transformation at a shifted lag.
• Combine: Joins two transformations with a binary operator (e.g., a ratio of two rolling means).

Pooled mode allows computing statistics across multiple series at once. Built-in rolling, expanding, seasonal-rolling, and exponentially weighted transforms support three pooling parameters:

• 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. These columns must be declared as static features during fit or preprocess. Series in the same group share the feature value; different groups get different values.
• partition_by: Sequence[str]: Column names to partition further along a dynamic (time-varying) key (e.g., promo or regime).

Rules and Composition:

• global_ and groupby are mutually exclusive.
• partition_by can compose with global_, groupby, or stand alone (local mode).
• All pooled modes require every series to end at the same timestamp.
• RANGE semantics: Pooled transforms use SQL-style RANGE BETWEEN ... PRECEDING windows over actual timestamps. They assume a continuous, gap-free time grid within each series. Combining validate_data=False with a pooled transform will raise a UserWarning.

The MLForecast object follows the scikit-learn API pattern (.fit() and .predict()). It automates feature engineering (lags, transformations, date features) and trains multiple models simultaneously.

Workflow:

1. Define Models: Provide a list of regressors that implement the scikit-learn API (e.g., LGBMRegressor, LinearRegression).
2. Instantiate MLForecast: Specify the models, frequency (freq), lags, lag transformations, date features, and target transformations.
3. Fit: Call .fit(series) to compute features and train models.
4. Predict: Call .predict(n) to generate forecasts for the next n steps using a recursive strategy.

import lightgbm as lgb
from sklearn.linear_model import LinearRegression
from mlforecast import MLForecast
from mlforecast.lag_transforms import ExpandingMean, RollingMean
from mlforecast.target_transforms import Differences

# 1. Define models
models = [
    lgb.LGBMRegressor(random_state=0, verbosity=-1),
    LinearRegression(),
]

# 2. Instantiate MLForecast
fcst = MLForecast(
    models=models,
    freq='D',
    lags=[7, 14],
    lag_transforms={
        1: [ExpandingMean()],
        7: [RollingMean(window_size=28)]
    },
    date_features=['dayofweek'],
    target_transforms=[Differences([1])],
)

# 3. Training
fcst.fit(series)

# 4. Predicting
predictions = fcst.predict(14)

AutoMLForecast is a high-level class that automates the process of selecting and tuning multiple forecasting models. It allows you to pass a dictionary of models (including specialized Auto versions of models like AutoLightGBM or AutoXGBoost) and automatically optimizes them using hyperparameter tuning.

Key features include:

• Model Ensemble/Selection: Pass multiple models to the models argument.
• Hyperparameter Tuning: Use fit_config to define tuning logic (e.g., specifying static features).
• Backtesting: Use n_windows in .fit() to perform cross-validation/backtesting.
• Prediction Intervals: Integrate PredictionIntervals to generate uncertainty bounds.
• Data Support: Works with both pandas and polars DataFrames.

from mlforecast.auto import AutoMLForecast, AutoLightGBM, AutoRidge
from mlforecast.utils import PredictionIntervals

# Initialize AutoMLForecast
auto_mlf = AutoMLForecast(
    freq=1,
    season_length=season_length,
    models={
        'lgb': AutoLightGBM(),
        'ridge': AutoRidge(),
    },
    fit_config=lambda trial: {'static_features': ['unique_id']},
    num_threads=2,
)

# Fit with backtesting and prediction intervals
auto_mlf.fit(
    df=train,
    n_windows=2,
    h=h,
    num_samples=2,
    optimize_kwargs={'timeout': 60},
    fitted=True,
    prediction_intervals=PredictionIntervals(n_windows=2, h=h),
)

# Predict future values
forecast = auto_mlf.predict(h, level=[80])

The LightGBMCV class emulates LightGBM's cv function by training several Boosters simultaneously on different data partitions. This allows for estimating error by iteration, which is useful for early stopping and finding the optimal number of boosting iterations.

Key features include:

• Error Estimation: Computes predictions for the whole test period to report error.
• Early Stopping: Supports stopping training if performance doesn't improve.
• Ensemble Predictions: predict() returns predictions from every model trained across the windows.
• CV Predictions: Access validation fold predictions via the cv_preds_ attribute.

To use it, initialize LightGBMCV with your frequency, lags, and transforms, then call .fit() with configuration parameters like n_windows and h (horizon).

from mlforecast.models import LightGBMCV

# Configuration for fitting
static_fit_config = dict(
    n_windows=2,
    h=horizon,
    params={'verbose': -1},
    compute_cv_preds=True,
)

# Initialize
cv = LightGBMCV(
    freq=1,
    lags=[24 * (i+1) for i in range(7)],
)

# Fit the model
hist = cv.fit(train, **static_fit_config)

# Get predictions from all trained boosters
preds = cv.predict(horizon)