OpenParable
Skip to content
← Back to skills

Deep Learning Forecasting

Development
deep-learning-forecasting

Deep Learning Forecasting is an Agent Skill for development published in the skforecast/skforecast repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Forecasts time series using recurrent neural networks (RNN, LSTM, GRU) with ForecasterRnn and the create_and_compile_model helper. Covers model architecture, training, and multi-series deep learning. Use when the user wants to use deep learning / neural networks for time series forecasting.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/skforecast/skforecast/blob/HEAD/skills/deep-learning-forecasting/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/deep-learning-forecasting, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Deep Learning Forecasting (RNN/LSTM)

References

See references/architecture-options.md for the complete create_and_compile_model signature, recurrent layer types, output shape rules, exog architecture, custom Keras model requirements, and fit_kwargs options.

When to Use

Use ForecasterRnn when:

  • You have large datasets (thousands of observations)
  • Complex nonlinear patterns that tree-based models struggle with
  • Multi-series problems where series share deep temporal patterns

Requirements: pip install skforecast[deeplearning] (installs keras)

Related skills

  • Before: choosing-a-forecaster (confirm ForecasterRnn is the right choice for the data size and pattern)
  • Before: feature-engineering (RNN models still benefit from cyclical / calendar exogenous features)
  • After: hyperparameter-optimization (tune RNN architecture and training hyperparameters)
  • After: prediction-intervals (only conformal intervals are supported for ForecasterRnn)

Stop Conditions

Scan before writing code. Each row lists a rule, the symptom when it is broken, and the recovery. Full pitfall catalog: the troubleshooting-common-errors skill.

RuleSymptomRecovery
lags in ForecasterRnn must match create_and_compile_model(..., lags=...)Input shape mismatch error during fitUse the same lags value in both calls
ForecasterRnn supports only method='conformal' for intervalsError when calling predict_interval(method='bootstrapping')Use method='conformal'
Pass exog to create_and_compile_model if exog is used in fit() / predict()Architecture mismatch or failure when predicting with exogBuild the model with the same exog you train on
Scale inputs with transformer_series=MinMaxScaler()Poor convergence; RNNs are scale-sensitiveAlways set a scaler on transformer_series

Quick Start

import pandas as pd
from skforecast.deep_learning import ForecasterRnn, create_and_compile_model
from sklearn.preprocessing import MinMaxScaler

# 1. Prepare data (DataFrame with DatetimeIndex, columns = series)
series = pd.read_csv('data.csv', index_col='date', parse_dates=True)
series = series.asfreq('h')

# 2. Create and compile a Keras model
model = create_and_compile_model(
    series=series,
    lags=48,
    steps=24,
    levels=series.columns.tolist(),  # All series
    recurrent_layer='LSTM',          # 'LSTM', 'GRU', or 'RNN'
    recurrent_units=[64, 32],        # Units per recurrent layer
    dense_units=[32],                # Units per dense layer
    compile_kwargs={'optimizer': 'adam', 'loss': 'mse'},
)

# 3. Create forecaster
forecaster = ForecasterRnn(
    levels=series.columns.tolist(),
    lags=48,
    estimator=model,
    transformer_series=MinMaxScaler(feature_range=(0, 1)),
    fit_kwargs={'epochs': 50, 'batch_size': 32, 'verbose': 0},
)

# 4. Train
forecaster.fit(series=series)

# 5. Predict
predictions = forecaster.predict(steps=24)

Model Architecture with create_and_compile_model

from skforecast.deep_learning import create_and_compile_model

# Simple LSTM
model = create_and_compile_model(
    series=series,
    lags=48,
    steps=24,
    levels='target',
    recurrent_layer='LSTM',
    recurrent_units=[64],
    dense_units=[32],
    compile_kwargs={'optimizer': 'adam', 'loss': 'mse'},
)

# Stacked LSTM (multiple recurrent layers)
model = create_and_compile_model(
    series=series,
    lags=48,
    steps=24,
    levels=series.columns.tolist(),
    recurrent_layer='LSTM',
    recurrent_units=[128, 64, 32],  # 3 stacked LSTM layers
    dense_units=[64, 32],           # 2 dense layers
    compile_kwargs={'optimizer': 'adam', 'loss': 'mse'},
)

# GRU variant (faster training)
model = create_and_compile_model(
    series=series,
    lags=48,
    steps=24,
    levels='target',
    recurrent_layer='GRU',
    recurrent_units=[64],
    dense_units=[32],
    compile_kwargs={'optimizer': 'adam', 'loss': 'mse'},
)

# Advanced: customize layer kwargs
model = create_and_compile_model(
    series=series,
    lags=48,
    steps=24,
    levels=series.columns.tolist(),
    recurrent_layer='LSTM',
    recurrent_units=[128, 64],
    recurrent_layers_kwargs={'activation': 'tanh'},   # default
    dense_units=[64],
    dense_layers_kwargs={'activation': 'relu'},        # default
    output_dense_layer_kwargs={'activation': 'linear'}, # default
    compile_kwargs={'optimizer': 'adam', 'loss': 'mse'},
    model_name='my_lstm_model',
)

With Exogenous Variables

When using exogenous variables, pass exog to create_and_compile_model so it builds the correct architecture (uses TimeDistributed layers internally).

# exog must be a DataFrame covering the training period
exog = pd.DataFrame({'temperature': [...], 'holiday': [...]}, index=series.index)

model = create_and_compile_model(
    series=series,
    lags=48,
    steps=24,
    levels=series.columns.tolist(),
    exog=exog,                        # Passes exog info to build architecture
    recurrent_layer='LSTM',
    recurrent_units=[64, 32],
    dense_units=[32],
    compile_kwargs={'optimizer': 'adam', 'loss': 'mse'},
)

forecaster = ForecasterRnn(
    levels=series.columns.tolist(),
    lags=48,
    estimator=model,
    fit_kwargs={'epochs': 50, 'batch_size': 32, 'verbose': 0},
)

forecaster.fit(series=series, exog=exog)
predictions = forecaster.predict(steps=24, exog=exog_test)  # exog_test covers forecast horizon

Custom Keras Model

import keras

# Build your own model for full control (single level, no exog)
# Output units = steps * n_levels. For 1 level: steps. For N levels: steps * N + Reshape.
inputs = keras.layers.Input(shape=(48, 1))  # (lags, n_features)
x = keras.layers.LSTM(64, return_sequences=True)(inputs)
x = keras.layers.LSTM(32)(x)
x = keras.layers.Dense(32, activation='relu')(x)
outputs = keras.layers.Dense(24)(x)  # steps * n_levels (here 24 * 1)

model = keras.Model(inputs=inputs, outputs=outputs)
model.compile(optimizer='adam', loss='mse')

forecaster = ForecasterRnn(
    levels='target',
    lags=48,
    estimator=model,
    transformer_series=MinMaxScaler(feature_range=(0, 1)),
    fit_kwargs={'epochs': 100, 'batch_size': 32},
)

Multi-series custom model: For N levels, the output layer should be Dense(steps * n_levels) followed by Reshape((steps, n_levels)).

Prediction Intervals

# ForecasterRnn supports conformal prediction only
forecaster.fit(series=series, store_in_sample_residuals=True)

predictions = forecaster.predict_interval(
    steps=24,
    method='conformal',           # Only 'conformal' supported
    interval=[0.1, 0.9],
    use_in_sample_residuals=True,
    use_binned_residuals=True,    # Better calibration with binned residuals
)

Backtesting

from skforecast.model_selection import backtesting_forecaster_multiseries, TimeSeriesFold

cv = TimeSeriesFold(
    steps=24,
    initial_train_size=len(series) - 200,
    refit=False,  # Retraining RNNs is expensive; set True only if needed
)

metric, predictions = backtesting_forecaster_multiseries(
    forecaster=forecaster,
    series=series,
    cv=cv,
    metric='mean_absolute_error',
)

Common Mistakes

  1. Not scaling data: RNNs are sensitive to scale. Always use transformer_series=MinMaxScaler().
  2. Too few epochs: Deep learning needs more training iterations. Start with 50-100 epochs.
  3. Wrong input shape: The lags parameter in ForecasterRnn and create_and_compile_model must match.
  4. Refit=True in backtesting: Retraining RNNs at every fold is very slow — use refit=False or refit=5.
  5. No GPU: Training is slow on CPU. Use GPU if available.
  6. Using predict_interval(method='bootstrapping'): ForecasterRnn only supports method='conformal'.
  7. Forgetting exog in create_and_compile_model: If you use exog in fit()/predict(), you must also pass exog when building the model so the architecture accounts for the extra input features.