StatsForecast Cheat Sheet

1Install & data format2.x

pip install statsforecast★
Numba-compiled — the first call warms up the JIT, then it's very fast.
# long DataFrame: one row per (series, timestamp) df.columns == ["unique_id", "ds", "y"]★
The Nixtla format: unique_id identifies the series, ds is the timestamp, y the value. Many series just stack more rows.
df = pd.read_parquet(...) # pandas OR polars both accepted
ds should be a datetime (or int for integer freq). Polars DataFrames work end-to-end.
from statsforecast.utils import generate_series df = generate_series(n_series=1000)
Quickly synthesize many series for experiments/benchmarks.

2The StatsForecast objectthe engine

from statsforecast import StatsForecast from statsforecast.models import AutoARIMA, AutoETS★
Import the engine and the models you want to run.
sf = StatsForecast(models=[AutoARIMA(season_length=12), AutoETS(season_length=12)], freq="M", n_jobs=-1)★
Pass a list of models — each becomes an output column. freq is a pandas offset alias; n_jobs=-1 uses all cores.
StatsForecast(models=[...], freq="D", fallback_model=Naive())
fallback_model is used for any series where the main model fails to fit — robust for huge, messy panels.

3Model zoofrom statsforecast.models

AutoARIMA(season_length=12)★
Automatic (S)ARIMA order selection — the fastest AutoARIMA in Python and the pmdarima replacement.
AutoETS(season_length=7) · AutoCES() · AutoTheta()★
Auto exponential smoothing / complex exponential smoothing / Theta — all self-tuning.
SeasonalNaive(season_length=7) · Naive() · WindowAverage(window_size=7)★
Cheap, strong baselines — always include one to benchmark against.
HoltWinters() · TBATS() · DynamicOptimizedTheta() · GARCH() · ADIDA()
Specialized models incl. intermittent-demand (ADIDA, CrostonClassic, IMAPA) and volatility (GARCH/ARCH).

4Seasonality & MSTLmultiple seasons

AutoARIMA(season_length=24) # hourly data w/ daily seasonality★
season_length is periods per cycle: 12 (monthly/yearly), 7 (daily/weekly), 24 (hourly/daily).
MSTL(season_length=[24, 24*7], trend_forecaster=AutoARIMA())★
Multiple-seasonal decomposition (e.g. daily + weekly) — pass a list of season lengths and a model for the trend.
alias="my_arima" # AutoARIMA(..., alias="my_arima")
Name a model so its output column is readable (and to run the same model with different params).

5forecast vs fit/predicttwo styles

fcst = sf.forecast(df=df, h=12)★
Recommended. Fits and predicts in one shot without storing state — the fastest path for many series. Output has unique_id, ds + one column per model.
sf.fit(df=df); fcst = sf.predict(h=12)
Stateful alternative when you want to keep the fitted models around (e.g. to predict repeatedly).
sf.forecast(df=df, h=12, fitted=True) sf.forecast_fitted_values()
fitted=True stores in-sample predictions — retrieve them to inspect residuals.
fcst.head() # columns: unique_id, ds, AutoARIMA, AutoETS, ...
Each model is its own column — ensembling is just averaging columns.

6Prediction intervalsuncertainty

sf.forecast(df=df, h=12, level=[80, 95])★
Adds AutoARIMA-lo-95, AutoARIMA-hi-95, etc. columns per model & level.
from statsforecast.utils import ConformalIntervals AutoARIMA(prediction_intervals=ConformalIntervals(n_windows=3))★
Distribution-free conformal intervals — calibrated on backtest windows; work for any model.
level=[90] # symmetric around the point forecast
Levels are coverage percentages. Native model intervals assume the model's error distribution; conformal ones don't.

7Exogenous featuresextra regressors

# add feature columns alongside y in df df.columns == ["unique_id","ds","y","price","promo"]★
Supported by models like AutoARIMA (regression with ARIMA errors). Extra columns are treated as regressors.
sf.forecast(df=df, h=12, X_df=future_X)★
You must supply the future values of the exogenous features (X_df) covering the horizon.
not every model uses exogenouscheck
Baselines (Naive/SeasonalNaive) ignore extra columns — use AutoARIMA/MSTL for regressor support.

8Cross-validationbacktest

cv = sf.cross_validation(df=df, h=12, n_windows=3, step_size=12)★
Rolling-origin backtest across n_windows cutoffs — the honest way to compare models. Output has cutoff, y, and each model's forecast.
from utilsforecast.losses import mape, rmse, mae from utilsforecast.evaluation import evaluate evaluate(cv, metrics=[mape, rmse])★
Score the CV results per series/model with utilsforecast — then pick the winner per series.
n_windows=5, step_size=1 # more, tighter backtest windows
More windows = more robust estimate, more compute. Keep h equal to your real forecast horizon.

9Plotting & distributedinspect & scale out

sf.plot(df, fcst, unique_ids=["id1"], level=[95])★
Quick plot of history + forecast (+ intervals) for selected series.
# pass a Spark / Dask / Ray DataFrame as df — same API sf.forecast(df=spark_df, h=12)★
Distributed backends: hand a Spark/Dask/Ray DataFrame to the same methods to forecast across a cluster.
StatsForecast(models=[...], freq="D", n_jobs=-1)
On one machine, n_jobs parallelizes across series — the main scaling knob before you need a cluster.

!Common gotchasread before shipping

exact column names
Columns must be unique_id, ds, y (v1 required these; v2 lets you override via args, but the defaults are these). Wrong names are the #1 error.
freq must match your data
freq is a pandas offset ("D", "M", "h") or an int for integer timestamps — a mismatch produces wrong ds in the forecast.
season_length is periods, not a string
It's the number of steps per cycle (7, 12, 24), not "weekly". Wrong seasonality quietly wrecks accuracy.
first call is slow (numba JIT)
Compilation happens once. Benchmark the second run, not the first.

StatsForecast cheat sheet