NeuralForecast: Deep Learning for Time Series Forecasting

3.1.7 · active · verified Thu Apr 16

NeuralForecast is an active Python library (current version 3.1.7) providing a comprehensive suite of state-of-the-art deep learning models for time series forecasting. It emphasizes performance, usability, and robustness, offering implementations of various architectures from classic RNNs to modern transformers. The library maintains a frequent release cadence, with several patch releases within major versions addressing features, bug fixes, and documentation improvements.

Common errors

```
KeyError: "['unique_id', 'ds', 'y'] not in index"
```
cause The input pandas DataFrame is missing one or more of the required columns: `unique_id`, `ds`, or `y`.

fix Rename your DataFrame columns to `unique_id`, `ds`, `y` or ensure they are present. For a single series, add a `unique_id` column with a constant value (e.g., `df['unique_id'] = 1`).
```
RuntimeError: Unable to load model. Model architecture from previous versions (pre-v3.0.0) cannot be loaded after the v3.0.0 API unification for recurrent models.
```
cause Attempting to load a pre-v3.0.0 saved recurrent model checkpoint (e.g., LSTM, GRU) into NeuralForecast v3.0.0 or later.

fix Re-train your models using NeuralForecast v3.0.0 or a newer version and save the checkpoints. Pre-v3.0.0 recurrent model checkpoints are incompatible with the new API.
```
FutureWarning: `max_epochs` is deprecated as of v1.7.0 and will be removed in a future release. Please use `max_steps` instead.
```
cause You are still using the `max_epochs` parameter in your model configuration, which is being phased out.

fix Replace `max_epochs` with `max_steps` when initializing your NeuralForecast models (e.g., `NBEATS(max_steps=500)` instead of `NBEATS(max_epochs=10)`).
```
TypeError: 'Trainer' object has no attribute 'callbacks' or other PyTorch/Lightning related API incompatibility errors.
```
cause Incompatibility between the installed versions of `neuralforecast`, `torch`, and/or `pytorch-lightning`.

fix Check the `neuralforecast` documentation or GitHub releases for the recommended compatible versions of `torch` and `pytorch-lightning`. Pin these dependencies in your environment (e.g., `pip install torch==2.1.0 pytorch-lightning==2.1.0 neuralforecast==3.1.7`).

Warnings

breaking NeuralForecast v3.0.0 introduced significant API changes, including unified API, all models inheriting `BaseModel`, recurrent models requiring an `input_size` parameter, and TCN/DRNN becoming window models. Loading recurrent models saved with pre-v3.0.0 versions is not supported.
Fix: Review your model implementations and saved checkpoints. Adapt to the new API structure (e.g., `BaseModel` inheritance, `input_size` for recurrent models). Re-train models saved with older versions if necessary.
gotcha The input DataFrame for `NeuralForecast.fit()` and `NeuralForecast.predict()` must be in a 'long' format with specific column names: `unique_id` (series identifier), `ds` (datestamp/temporal index), and `y` (target variable). Missing or incorrectly named columns will cause errors.
Fix: Ensure your pandas DataFrame has the columns `['unique_id', 'ds', 'y']`. For single time series, assign a common `unique_id` (e.g., `1`) to all rows. Convert `ds` to datetime objects for proper handling.
deprecated The `max_epochs` parameter for model training is being deprecated in favor of `max_steps`. While it may still work, using `max_steps` is the recommended approach for defining training iterations.
Fix: Replace `max_epochs` with `max_steps` when defining your models to ensure future compatibility and fine-grained control over training.
gotcha NeuralForecast has shown sensitivity to `pytorch` and `pytorch-lightning` versions. Incompatible versions can lead to runtime errors or unexpected behavior. For example, `neuralforecast >=1.7.2` required `pytorch-lightning >=2.1.0`, and `v3.0.1` specified `2.0.0 <= pytorch <= 2.6.0`.
Fix: Always check the `neuralforecast` documentation or release notes for recommended `pytorch` and `pytorch-lightning` versions. If encountering issues, try pinning these dependencies to known compatible ranges.

Install

pip install neuralforecast PyPI
conda install -c conda-forge neuralforecast Conda-Forge

Imports

NeuralForecast

from neuralforecast import NeuralForecast

LSTM
```
from neuralforecast.models import LSTM
```
Or other models like NHITS, NBEATS, DeepAR, etc.

AirPassengersDF

from neuralforecast.utils import AirPassengersDF

Utility for loading example data.

MQLoss

from neuralforecast.losses.pytorch import MQLoss

Or other PyTorch-based loss functions.

AutoNHITS
```
from neuralforecast.auto import AutoNHITS
```
For automated hyperparameter tuning variants of models.

Quickstart

This quickstart demonstrates how to load a sample dataset, define a NeuralForecast model (NBEATS in this case), fit it to the data, and generate predictions. The input DataFrame must contain 'unique_id', 'ds' (datestamp), and 'y' (target variable) columns. The `freq` parameter is crucial for time series interpretation.

import pandas as pd
from neuralforecast import NeuralForecast
from neuralforecast.models import NBEATS
from neuralforecast.utils import AirPassengersDF

# 1. Load data
Y_df = AirPassengersDF # Example dataset with 'unique_id', 'ds', 'y' columns

# 2. Define forecasting horizon
horizon = 12

# 3. Instantiate and fit model
nf = NeuralForecast(
    models=[NBEATS(input_size=2 * horizon, h=horizon, max_steps=500)],
    freq='ME' # Monthly End frequency
)
nf.fit(df=Y_df)

# 4. Make predictions
Y_hat_df = nf.predict()

print(Y_hat_df.head())

view raw JSON →