NBEATS
用于可解释时间序列预测的神经基扩展分析

TensorFlow/PyTorch 实现 | 论文 | 结果

NBEATS 的通用层和可解释层的输出

安装

可以同时安装两个后端。

从 PyPI

安装 TensorFlow/Keras 后端：pip install nbeats-keras

安装 PyTorch 后端：pip install nbeats-pytorch

从源代码

安装基于 Makefile。

使用 Keras 安装 N-Beats 的命令：make install-keras

使用 PyTorch 安装 N-Beats 的命令：make install-pytorch

在 GPU 上运行

在 TensorFlow 的最新版本中，此技巧已不再必要。若要强制使用 GPU（使用 Keras 后端），请执行：pip uninstall -y tensorflow && pip install tensorflow-gpu。

示例

以下示例可以帮助您熟悉这两个后端。请注意，目前只有 Keras 后端支持 input_dim>1。

import warnings

import numpy as np

from nbeats_keras.model import NBeatsNet as NBeatsKeras
from nbeats_pytorch.model import NBeatsNet as NBeatsPytorch

warnings.filterwarnings(action='ignore', message='Setting attributes')


def main():
    # https://keras.io/layers/recurrent/
    # 目前只有 Keras 支持 input_dim > 1。在原始论文中，input_dim=1。
    num_samples, time_steps, input_dim, output_dim = 50_000, 10, 1, 1

    # 本示例适用于 Keras 和 PyTorch。实际使用时，请选择您偏好的后端。
    for BackendType in [NBeatsKeras, NBeatsPytorch]:
        # 注意：如果您选择使用 input_dim>1 的 Keras 后端，则需要在此处（构造函数中）也设置该值。
        backend = BackendType(
            backcast_length=time_steps, forecast_length=output_dim,
            stack_types=(NBeatsKeras.GENERIC_BLOCK, NBeatsKeras.GENERIC_BLOCK),
            nb_blocks_per_stack=2, thetas_dim=(4, 4), share_weights_in_stack=True,
            hidden_layer_units=64
        )

        # 定义目标函数和优化器。
        backend.compile(loss='mae', optimizer='adam')

        # 定义数据。要解决的问题是找到 f，使得 | f(x) - y | -> 0。
        # 其中 f = np.mean。
        x = np.random.uniform(size=(num_samples, time_steps, input_dim))
        y = np.mean(x, axis=1, keepdims=True)

        # 将数据分为训练集和测试集。
        c = num_samples // 10
        x_train, y_train, x_test, y_test = x[c:], y[c:], x[:c], y[:c]
        test_size = len(x_test)

        # 训练模型。
        print('Training...')
        backend.fit(x_train, y_train, validation_data=(x_test, y_test), epochs=20, batch_size=128)

        # 保存模型以备后用。
        backend.save('n_beats_model.h5')

        # 对测试集进行预测（预测）。
        predictions_forecast = backend.predict(x_test)
        np.testing.assert_equal(predictions_forecast.shape, (test_size, backend.forecast_length, output_dim))

        # 对测试集进行预测（回溯）。
        predictions_backcast = backend.predict(x_test, return_backcast=True)
        np.testing.assert_equal(predictions_backcast.shape, (test_size, backend.backcast_length, output_dim))

        # 加载模型。
        model_2 = BackendType.load('n_beats_model.h5')

        np.testing.assert_almost_equal(predictions_forecast, model_2.predict(x_test))


if __name__ == '__main__':
    main()

浏览 examples 以获取更多内容。其中包含 Jupyter 笔记本。

Jupyter 笔记本：NBeats.ipynb：make run-jupyter。

引用

@misc{NBeatsPRemy,
  author = {Philippe Remy},
  title = {N-BEATS: Neural basis expansion analysis for interpretable time series forecasting},
  year = {2020},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/philipperemy/n-beats}},
}

贡献者

感谢！

N-BEATS 快速上手指南

N-BEATS（Neural Basis Expansion Analysis）是一种用于可解释时间序列预测的深度学习模型。本项目提供了 TensorFlow/Keras 和 PyTorch 两种后端实现。

环境准备

• 操作系统：Linux, macOS, Windows
• Python 版本：建议 Python 3.7+
• 依赖框架：
  • Keras 后端：需要安装 tensorflow 或 tensorflow-gpu
  • PyTorch 后端：需要安装 torch
• GPU 支持：若需使用 GPU 加速，请确保已安装对应的 CUDA 驱动及 GPU 版本的深度学习框架。

安装步骤

你可以通过 PyPI 直接安装，也可以从源码安装。

方式一：通过 PyPI 安装（推荐）

根据你需要的后端选择安装命令：

# 安装 Keras/TensorFlow 后端
pip install nbeats-keras

# 安装 PyTorch 后端
pip install nbeats-pytorch

提示：国内用户可使用清华或阿里镜像源加速安装：

pip install nbeats-keras -i https://pypi.tuna.tsinghua.edu.cn/simple
pip install nbeats-pytorch -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：从源码安装

如果你克隆了仓库，可以使用 Makefile 进行安装：

# 安装 Keras 版本
make install-keras

# 安装 PyTorch 版本
make install-pytorch

GPU 配置说明

对于较新版本的 TensorFlow，通常无需额外操作即可识别 GPU。若需强制使用 GPU 版本（旧版环境），可执行：

pip uninstall -y tensorflow && pip install tensorflow-gpu

基本使用

以下示例展示了如何同时使用 Keras 和 PyTorch 后端构建、训练并预测 N-BEATS 模型。

注意：目前仅 Keras 后端支持 input_dim > 1（多变量输入），PyTorch 后端暂仅支持单变量。

import warnings
import numpy as np

from nbeats_keras.model import NBeatsNet as NBeatsKeras
from nbeats_pytorch.model import NBeatsNet as NBeatsPytorch

warnings.filterwarnings(action='ignore', message='Setting attributes')


def main():
    # 参数设置
    num_samples, time_steps, input_dim, output_dim = 50_000, 10, 1, 1

    # 遍历两种后端进行演示（实际使用时任选其一）
    for BackendType in [NBeatsKeras, NBeatsPytorch]:
        # 初始化模型
        backend = BackendType(
            backcast_length=time_steps, 
            forecast_length=output_dim,
            stack_types=(NBeatsKeras.GENERIC_BLOCK, NBeatsKeras.GENERIC_BLOCK),
            nb_blocks_per_stack=2, 
            thetas_dim=(4, 4), 
            share_weights_in_stack=True,
            hidden_layer_units=64
        )

        # 编译模型
        backend.compile(loss='mae', optimizer='adam')

        # 生成模拟数据 (目标：预测输入序列的均值)
        x = np.random.uniform(size=(num_samples, time_steps, input_dim))
        y = np.mean(x, axis=1, keepdims=True)

        # 划分训练集和测试集
        c = num_samples // 10
        x_train, y_train, x_test, y_test = x[c:], y[c:], x[:c], y[:c]
        test_size = len(x_test)

        # 训练模型
        print('Training...')
        backend.fit(x_train, y_train, validation_data=(x_test, y_test), epochs=20, batch_size=128)

        # 保存模型
        backend.save('n_beats_model.h5')

        # 预测未来值 (Forecast)
        predictions_forecast = backend.predict(x_test)
        
        # 预测历史重构值 (Backcast)
        predictions_backcast = backend.predict(x_test, return_backcast=True)

        # 加载模型并验证
        model_2 = BackendType.load('n_beats_model.h5')
        np.testing.assert_almost_equal(predictions_forecast, model_2.predict(x_test))
        
        print(f"{BackendType.__name__} completed successfully.")


if __name__ == '__main__':
    main()

更多详细用例和 Jupyter Notebook 教程请参考项目仓库中的 examples 目录。运行 Notebook 命令：

make run-jupyter