文档 | 教程 | 发布说明

PyTorch Forecasting 是一个基于 PyTorch 的时间序列预测包，具有最先进的网络架构。它提供了用于在 pandas 数据框上训练网络的高级 API，并利用 PyTorch Lightning 在（多）GPU 和 CPU 上进行可扩展的训练以及自动记录。

我们在 Towards Data Science 上的文章介绍了该包并提供了背景信息。

PyTorch Forecasting 旨在简化使用神经网络进行现实世界应用和研究的最先进时间序列预测。目标是为专业人员提供最大灵活性的高级 API，并为初学者提供合理的默认设置。 具体来说，该包提供了

• 一个时间序列数据集类，抽象处理变量转换、缺失值、随机子采样、多种历史长度等。
• 一个基础模型类，提供基本的时间序列模型训练以及在 tensorboard 上记录和泛化的可视化，如实际 vs 预测和依赖关系图。
• 多个用于时间序列预测的神经网络架构，已针对现实世界部署进行了增强，并具有内置解释功能。
• 多重视角时间序列指标。
• 通过 optuna 进行超参数调优。

该包构建于 pytorch-lightning 之上，支持在 CPU、单 GPU 和多 GPU 上开箱即用地训练。

安装

如果你在 Windows 上工作，首先需要安装 PyTorch：

pip install torch -f https://download.pytorch.org/whl/torch_stable.html

否则，你可以继续执行：

pip install pytorch-forecasting

或者，你可以通过 conda 安装该包：

conda install pytorch-forecasting pytorch -c pytorch>=1.7 -c conda-forge

PyTorch Forecasting 现在从 conda-forge 频道安装，而 PyTorch 从 pytorch 频道安装。

要使用 MQF2 损失（多变量分位数损失），还需要安装：

pip install pytorch-forecasting[mqf2]

文档

访问 https://pytorch-forecasting.readthedocs.io 阅读详细教程的文档。

可用模型

文档提供了可用模型的比较。

• 用于解释性多重视角时间序列预测的时间融合变压器，在基准测试中比 Amazon 的 DeepAR 高出 36-69%。
• 用于可解释时间序列预测的神经基础扩展分析 N-BEATS，在 M4 竞赛中（如果用作集成）超过了包括传统统计方法的集成在内的所有其他方法。M4 竞赛可以算作最重要的单变量时间序列预测基准。
• 时间序列预测的神经分层插值 N-HiTS 支持协变量，并持续击败 N-BEATS。它尤其适合长视角预测。
• 带有自回归递归网络的概率预测 DeepAR 是最流行的预测算法之一，通常用作基准。
• 用于基准测试的简单标准网络：LSTM 和 GRU 网络，以及解码器上的 MLP。
• 一个总是预测最新已知值的基准模型。

要实现新模型或其他自定义组件，请参见 如何实现新模型教程，它涵盖了基础及高级架构。

使用示例

可以使用 PyTorch Lightning Trainer 在 pandas Dataframes 上训练网络，这些 Dataframes 首先会转换为 TimeSeriesDataSet。

# 训练导入
import lightning.pytorch as pl
from lightning.pytorch.loggers import TensorBoardLogger
from lightning.pytorch.callbacks import EarlyStopping, LearningRateMonitor
# 导入数据集、网络和优化指标
from pytorch_forecasting import TimeSeriesDataSet, TemporalFusionTransformer, QuantileLoss
from lightning.pytorch.tuner import Tuner

# 加载数据：这是包含至少一个目标列（你想要预测的内容）、时间序列 ID 列（应为唯一字符串以标识每个时间序列）和观察时间列（应为单调递增整数）的 pandas 数据帧
data = ...

# 定义数据集，即为 pandas 数据帧添加元数据，使模型能够理解它
max_encoder_length = 36
max_prediction_length = 6
training_cutoff = "YYYY-MM-DD"  # 截止日期

training = TimeSeriesDataSet(
    data[lambda x: x.date <= training_cutoff],
    time_idx= ...,  # 观察时间的列名
    target= ...,  # 预测目标的列名
    group_ids=[ ... ],  # 时间序列 ID 的列名（或列名列表）
    max_encoder_length=max_encoder_length,  # 使用的历史长度
    max_prediction_length=max_prediction_length,  # 预测未来的长度
    # 静态协变量
    static_categoricals=[ ... ],
    static_reals=[ ... ],
    # 已知和未知协变量，用于提供预测信息
    time_varying_known_categoricals=[ ... ],
    time_varying_known_reals=[ ... ],
    time_varying_unknown_categoricals=[ ... ],
    time_varying_unknown_reals=[ ... ],
)

# 使用与训练数据集相同的标准化技术创建验证数据集
validation = TimeSeriesDataSet.from_dataset(training, data, min_prediction_idx=training.index.time.max() + 1, stop_randomization=True)

# 转换数据集为训练的加载器
batch_size = 128
train_dataloader = training.to_dataloader(train=True, batch_size=batch_size, num_workers=2)
val_dataloader = validation.to_dataloader(train=False, batch_size=batch_size, num_workers=2)

# 使用早停创建 PyTorch Lightning Trainer
early_stop_callback = EarlyStopping(monitor="val_loss", min_delta=1e-4, patience=1, verbose=False, mode="min")
lr_logger = LearningRateMonitor()
trainer = pl.Trainer(
    max_epochs=100,
    accelerator="auto",  # 在 CPU 上运行，如果在多个 GPU 上运行，使用 strategy="ddp"
    gradient_clip_val=0.1,
    limit_train_batches=30,  # 每个 epoch 的训练批次数
    callbacks=[lr_logger, early_stop_callback],
    logger=TensorBoardLogger("lightning_logs")
)

# 定义要训练的网络 - 架构主要由数据集推断，因此用户只需设置少数超参数
tft = TemporalFusionTransformer.from_dataset(
    # 数据集
    training,
    # 架构超参数
    hidden_size=32,
    attention_head_size=1,
    dropout=0.1,
    hidden_continuous_size=16,
    # 要优化的损失指标
    loss=QuantileLoss(),
    # 记录频率
    log_interval=2,
    # 优化器参数
    learning_rate=0.03,
    reduce_on_plateau_patience=4
)
print(f"网络中的参数数量: {tft.size()/1e3:.1f}千")

# 找到最佳的学习率
res = Tuner(trainer).lr_find(
    tft, train_dataloaders=train_dataloader, val_dataloaders=val_dataloader, early_stop_threshold=1000.0, max_lr=0.3,
)
# 并绘制结果 - 总是需要视觉确认建议的学习率是否合理
print(f"建议的学习率: {res.suggestion()}")
fig = res.plot(show=True, suggest=True)
fig.show()

# 在数据上拟合模型 - 如有必要，以正确的学习率重新定义模型
trainer.fit(
    tft, train_dataloaders=train_dataloader, val_dataloaders=val_dataloader,
)