Deep-learning time-series forecasting on PyTorch Lightning · TFT / N-BEATS / DeepAR · verified against PyTorch Forecasting 1.x (2026)

PyTorch Forecasting cheat sheet

PyTorch Forecasting makes state-of-the-art deep forecasting practical: wrap a pandas DataFrame in a TimeSeriesDataSet (handling encoder/decoder windows, categorical encoding, normalization, and multiple series), build a model with .from_dataset(), and train it with the PyTorch Lightning Trainer. Flagship model is the Temporal Fusion Transformer (TFT) with built-in interpretability. This sheet targets PyTorch Forecasting 1.x (now under the sktime org).

setup & concept TimeSeriesDataSet models & training predict & interpret tuning gotcha ★ most common

Verified 2026-08-24 against the official docs at pytorch-forecasting.readthedocs.io and the sktime/pytorch-forecasting repo (1.x). Built on PyTorch Lightning; input is a long-format pandas DataFrame.

Outline

Almost all the work is in configuring the TimeSeriesDataSet correctly. Once that's right, model + Lightning training is boilerplate.

Data

The dataset object does the heavy lifting.

1Install & the flow1.x

pip install pytorch-forecasting★
Pulls in PyTorch Lightning. GPU strongly recommended for the transformer models.
# flow: DataFrame -> TimeSeriesDataSet -> model.from_dataset -> Trainer.fit -> predict★
Input is a long-format DataFrame: one row per (series, timestep), with a numeric time_idx.
from pytorch_forecasting import TimeSeriesDataSet, TemporalFusionTransformer
Plus import lightning.pytorch as pl for the Trainer.

2TimeSeriesDataSetthe core config

training = TimeSeriesDataSet( df[df.time_idx <= cutoff], time_idx="time_idx", target="sales", group_ids=["store", "item"], max_encoder_length=60, max_prediction_length=14)★
The essentials: time_idx (int), target, group_ids (what identifies each series), and the encoder (lookback) & prediction (horizon) window lengths.
static_categoricals=["store"], time_varying_known_reals=["time_idx", "price"], time_varying_unknown_reals=["sales"]★
Known covariates are available in the future (calendar, planned price); unknown are only observed up to now (the target, sensors). Getting this split right is critical.
target_normalizer=GroupNormalizer(groups=["store","item"])★
Normalize the target per series so a big store doesn't dominate — scaling is inverted automatically at predict time.
static_reals=..., time_varying_known_categoricals=..., add_relative_time_idx=True
Extra feature buckets + convenience flags (add_target_scales, add_encoder_length).

3Validation & dataloadersderive, don't rebuild

validation = TimeSeriesDataSet.from_dataset(training, df, predict=True, stop_randomization=True)★
Derive val/test from the training set so encoders/normalizers match exactly. predict=True = one forecast per series from the latest point.
train_dl = training.to_dataloader(train=True, batch_size=128, num_workers=4) val_dl = validation.to_dataloader(train=False, batch_size=256)★
Turn datasets into PyTorch dataloaders for the Trainer.

Model & Training

Build from the dataset, train with Lightning.

4from_dataset & modelsarchitecture

tft = TemporalFusionTransformer.from_dataset( training, learning_rate=0.03, hidden_size=32, attention_head_size=4, loss=QuantileLoss())★
Always build with .from_dataset() — it reads feature shapes/encoders from the dataset so the model matches your data.
from pytorch_forecasting import NBeats, DeepAR, NHiTS, RecurrentNetwork★
Model zoo: TFT (interpretable, covariates), N-BEATS/N-HiTS (univariate, fast), DeepAR (probabilistic RNN).
from pytorch_forecasting.metrics import QuantileLoss, MAE, RMSE, SMAPE, MQF2DistributionLoss
QuantileLoss gives prediction intervals; distribution losses for probabilistic forecasts.

5Train with Lightningpl.Trainer

import lightning.pytorch as pl from lightning.pytorch.callbacks import EarlyStopping trainer = pl.Trainer(max_epochs=30, accelerator="gpu", gradient_clip_val=0.1, callbacks=[EarlyStopping("val_loss", patience=5)])★
A standard Lightning Trainer — the model is a LightningModule. gradient_clip_val stabilizes the TFT.
trainer.fit(tft, train_dataloaders=train_dl, val_dataloaders=val_dl)★
Trains & validates. Checkpoints to lightning_logs/; monitor with TensorBoard.
best = TemporalFusionTransformer.load_from_checkpoint( trainer.checkpoint_callback.best_model_path)★
Reload the best checkpoint for prediction.

Predict & Interpret

Forecast, and understand the TFT.

6Predictforecast

preds = best.predict(val_dl)★
Point predictions (tensor). Use the same TimeSeriesDataSet pipeline for new data via from_dataset.
out = best.predict(val_dl, mode="raw", return_x=True)★
mode="raw" returns the full output (quantiles, attention); mode="quantiles" for intervals; return_x to keep inputs for plotting.
best.plot_prediction(out.x, out.output, idx=0, add_loss_to_title=True)★
Plot a forecast (with the prediction interval) for one series.
from pytorch_forecasting import Baseline Baseline().predict(val_dl) # naive last-value benchmark
Always compare against the Baseline before trusting a deep model.

7Interpret (TFT)why it forecasts

interp = best.interpret_output(out.output, reduction="sum") best.plot_interpretation(interp)★
TFT's headline feature: variable-importance & attention over time — which features & which past steps drove the forecast.
best.plot_prediction(..., add_loss_to_title=SMAPE())
Overlay a metric per plotted example to spot the worst series.

Optimize

Find a learning rate and tune.

8LR find & tuninghyperparameters

from lightning.pytorch.tuner import Tuner Tuner(trainer).lr_find(tft, train_dl, val_dl)★
Sweep learning rates — pick from the steepest-descent region, then set it on the model.
from pytorch_forecasting.models.temporal_fusion_transformer.tuning import optimize_hyperparameters★
Optuna-backed HPO over hidden size, dropout, LR, etc. — returns the best study.
hidden_size · attention_head_size · dropout · hidden_continuous_size
The knobs that matter most for the TFT; start small and scale up.

!Common gotchasread before shipping

known vs unknown reals
Putting the target or a not-known-ahead feature in time_varying_known_reals leaks the future. Only calendar/planned values are "known".
derive val with from_dataset
Building a separate TimeSeriesDataSet for validation risks mismatched encoders/normalizers. Always use from_dataset(training, ...).
contiguous integer time_idx
time_idx must be an increasing integer per series with no gaps — not a datetime. Convert first.
GroupNormalizer for multi-series
Without per-group normalization, large-magnitude series dominate the loss. Normalize by group_ids.
beat the Baseline
Deep models are easy to overfit on small data. If you don't beat Baseline(), the extra complexity isn't earning its keep.

Worth memorizing

DataFrame → TimeSeriesDataSet → from_dataset → Trainer.fitthe whole pipeline

group_ids identify each seriesencoder=lookback, prediction=horizon lengths

known vs unknown realsknown = available in the future; unknown = only up to now (incl. the target)

GroupNormalizer per seriesscaling inverted automatically at predict

from_dataset to derive val/testkeeps encoders & normalizers consistent

build models with .from_dataset()TFT / N-BEATS / N-HiTS / DeepAR

it's a LightningModuleplain pl.Trainer.fit; gradient_clip_val for TFT

predict(mode="raw") + interpret_outputTFT variable importance & attention

contiguous integer time_idxnot a datetime; no gaps

PyTorch Forecasting cheat sheet (pytorch_forecasting_cheatsheet v0).
Verified 2026-08-24 against pytorch-forecasting.readthedocs.io and sktime/pytorch-forecasting (1.x). Deep time-series forecasting on PyTorch Lightning: TimeSeriesDataSet handles windowing/encoding/normalization; models (TFT, N-BEATS, N-HiTS, DeepAR) build via from_dataset; the TFT adds interpretability. For classical/scalable forecasting see StatsForecast/sktime/Darts. Model & API names evolve — check the docs.
Design system = shared cheat-sheet tokens (Inter + JetBrains Mono, light theme). Content only.

Outline

Data

Model

Use

Optimize

Data

Model & Training

Predict & Interpret

Optimize

Worth memorizing