{"id":9264,"library":"pytorch-forecasting","title":"PyTorch Forecasting","description":"PyTorch Forecasting is a highly scalable open-source library for state-of-the-art time series forecasting with PyTorch. It provides common data structures like TimeSeriesDataSet, various forecasting models (e.g., TFT, DeepAR, N-BEATS), normalizers, and metrics, all integrated with PyTorch Lightning for efficient training. The current version is 1.7.0, with regular updates aligning with PyTorch and PyTorch Lightning developments. It requires Python versions >=3.10 and <3.15.","status":"active","version":"1.7.0","language":"en","source_language":"en","source_url":"https://github.com/jdb78/pytorch-forecasting","tags":["pytorch","timeseries","forecasting","deep-learning","machine-learning"],"install":[{"cmd":"pip install pytorch-forecasting","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core dependency for training infrastructure and GPU acceleration.","package":"pytorch-lightning","optional":false},{"reason":"Recommended for hyperparameter optimization.","package":"optuna","optional":true}],"imports":[{"note":"The data module path was refactored in versions >=0.9.0/1.0.0; the older path is deprecated.","wrong":"from pytorch_forecasting.data.timeseries import TimeSeriesDataSet","symbol":"TimeSeriesDataSet","correct":"from pytorch_forecasting.data import TimeSeriesDataSet"},{"symbol":"TemporalFusionTransformer","correct":"from pytorch_forecasting.models import TemporalFusionTransformer"},{"symbol":"DeepAR","correct":"from pytorch_forecasting.models import DeepAR"},{"symbol":"GroupNormalizer","correct":"from pytorch_forecasting.data import GroupNormalizer"},{"note":"Since version 1.0.0, the Trainer class is directly imported from PyTorch Lightning, not pytorch_forecasting.","wrong":"from pytorch_forecasting.trainer import Trainer","symbol":"Trainer","correct":"from pytorch_lightning.trainer import Trainer"}],"quickstart":{"code":"import pandas as pd\nimport pytorch_lightning as pl\nfrom pytorch_forecasting import TimeSeriesDataSet, TemporalFusionTransformer\nfrom pytorch_forecasting.data import GroupNormalizer\nfrom pytorch_forecasting.metrics import MAE\n\n# 1. Create dummy data\ndata = pd.DataFrame(dict(\n    time_idx=pd.to_datetime(pd.date_range(\"2020-01-01\", periods=100)),\n    value=range(100),\n    group=[\"a\"] * 50 + [\"b\"] * 50,\n    static_cat=[\"x\"] * 100,\n    known_cont=[i for i in range(100)]\n))\ndata[\"time_idx\"] = (data[\"time_idx\"] - data[\"time_idx\"].min()).dt.days\n\nmax_encoder_length = 20\nmax_prediction_length = 5\ntraining_cutoff = data[\"time_idx\"].max() - max_prediction_length\n\n# 2. Define TimeSeriesDataSet\ntraining = TimeSeriesDataSet(\n    data[lambda x: x.time_idx <= training_cutoff],\n    time_idx=\"time_idx\",\n    target=\"value\",\n    group_ids=[\"group\"],\n    min_encoder_length=max_encoder_length // 2,\n    max_encoder_length=max_encoder_length,\n    min_prediction_length=1,\n    max_prediction_length=max_prediction_length,\n    static_categoricals=[\"static_cat\"],\n    time_varying_known_reals=[\"time_idx\", \"known_cont\"],\n    time_varying_unknown_reals=[\"value\"],\n    target_normalizer=GroupNormalizer(groups=[\"group\"], transformation=\"softplus\"),\n    add_relative_time_idx=True,\n    add_target_scales=True,\n    add_encoder_length=True,\n)\n# create validation set (predict=True) which means to predict the last max_prediction_length points in time\nvalidation = TimeSeriesDataSet.from_dataset(training, data, predict=True, stop_index=training_cutoff)\ntrain_dataloader = training.to_dataloader(batch_size=4, num_workers=0)\nval_dataloader = validation.to_dataloader(batch_size=4, num_workers=0)\n\n# 3. Define model\ntft = TemporalFusionTransformer.from_dataset(\n    training,\n    learning_rate=0.03,\n    hidden_size=16,\n    attention_head_size=1,\n    dropout=0.1,\n    hidden_continuous_size=8,\n    output_size=7, # 7 quantiles by default\n    loss=MAE(), # Can also use QuantileLoss()\n    log_interval=10,\n    reduce_on_plateau_patience=4,\n)\n\n# 4. Train model\ntrainer = pl.Trainer(\n    max_epochs=1, # Reduced for quickstart\n    gradient_clip_val=0.1,\n)\ntrainer.fit(\n    tft,\n    train_dataloaders=train_dataloader,\n    val_dataloaders=val_dataloader,\n)\n\n# 5. Make predictions\nbest_model_path = trainer.checkpoint_callback.best_model_path\nbest_tft = TemporalFusionTransformer.load_from_checkpoint(best_model_path)\nraw_predictions, x = best_tft.predict(val_dataloader, mode=\"raw\", return_x=True)\n# print(raw_predictions[\"prediction\"].shape)\n# print(best_tft.calculate_metrics(x, raw_predictions, metrics=[MAE()]))","lang":"python","description":"Demonstrates basic usage of PyTorch Forecasting with `TemporalFusionTransformer`, from dummy data generation, data preparation using `TimeSeriesDataSet`, to model definition, training with `pytorch_lightning.Trainer`, and making predictions."},"warnings":[{"fix":"Change your import statement from `from pytorch_forecasting.trainer import Trainer` to `from pytorch_lightning.trainer import Trainer`.","message":"The `Trainer` class is now directly imported from `pytorch_lightning` instead of `pytorch_forecasting.trainer`.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Explicitly pass `max_encoder_length` and `max_prediction_length` to the `TimeSeriesDataSet` constructor, ensuring they align with your data characteristics and forecasting horizon.","message":"The `TimeSeriesDataSet` constructor now requires `max_encoder_length` and `max_prediction_length` as mandatory arguments.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Ensure `group_ids` uniquely identify each individual time series and `time_idx` is a monotonically increasing integer within each group. Use a simple integer sequence for `time_idx` (e.g., `(df['date'] - df['date'].min()).dt.days`).","message":"Incorrectly defining `group_ids` or `time_idx` in `TimeSeriesDataSet` can lead to data integrity errors or incorrect time series splitting.","severity":"gotcha","affected_versions":"All"},{"fix":"Update import paths from `pytorch_forecasting.data.timeseries.XYZ` to `pytorch_forecasting.data.XYZ`.","message":"Many top-level `pytorch_forecasting.data.timeseries` imports were moved directly to `pytorch_forecasting.data` for simplification.","severity":"deprecated","affected_versions":">=1.0.0"},{"fix":"Always convert your `TimeSeriesDataSet` into a `DataLoader` first (e.g., `validation_dataloader = validation_dataset.to_dataloader(batch_size=...)`) and then pass the `DataLoader` to `model.predict()`.","message":"The `predict` method of models expects a `DataLoader` as input, not a raw `TimeSeriesDataSet` or a Pandas DataFrame.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Change your import statement from `from pytorch_forecasting.trainer import Trainer` to `from pytorch_lightning.trainer import Trainer`.","cause":"The `Trainer` class was moved from `pytorch_forecasting` to `pytorch_lightning` directly since version 1.0.0.","error":"ModuleNotFoundError: No module named 'pytorch_forecasting.trainer'"},{"fix":"Add `max_encoder_length` and `max_prediction_length` to your `TimeSeriesDataSet` constructor call, ensuring they align with your data characteristics.","cause":"In versions 1.0.0 and above, `max_encoder_length` and `max_prediction_length` became mandatory arguments for `TimeSeriesDataSet`.","error":"TypeError: TimeSeriesDataSet.__init__ missing 2 required positional arguments: 'max_encoder_length', 'max_prediction_length'"},{"fix":"Ensure you pass a list of column names (e.g., `['your_group_column']`) to the `group_ids` parameter in `TimeSeriesDataSet` that uniquely identify each time series in your dataset.","cause":"The `group_ids` parameter in `TimeSeriesDataSet` is crucial for identifying individual time series when multiple series are present in the dataset, or even a single series.","error":"ValueError: group_ids must be specified and contain at least one column"},{"fix":"Convert your `TimeSeriesDataSet` object into a `DataLoader` using `.to_dataloader()` (e.g., `validation_dataloader = validation_dataset.to_dataloader(batch_size=...)`) and then pass this `DataLoader` to the model's `predict` method.","cause":"The `predict` method of a model (e.g., `TemporalFusionTransformer`) expects a PyTorch `DataLoader` containing the data for prediction, not a raw `TimeSeriesDataSet` object.","error":"AttributeError: 'TimeSeriesDataSet' object has no attribute 'predict'"}]}