用于时间序列预测、分类和异常检测的深度学习

Flow Forecast (FF) 是一个开源的时间序列预测深度学习框架。它提供了所有最新的最先进模型（Transformer、注意力机制模型、GRU、常微分方程等）以及前沿概念，并配有易于理解的可解释性指标、云服务提供商集成和模型部署能力。Flow Forecast 是首个支持基于 Transformer 模型的时间序列框架，至今仍是唯一真正的端到端时间序列深度学习框架。目前，该仓库主要由 CoronaWhy 的 Task-TS 维护。欢迎提交 Pull 请求。历史上，该仓库曾提供用于山洪和河流流量预测的开源基准测试和代码。

如需更多教程和示例，请参阅我们的 教程仓库。

分支	状态 $$
master
Build PY
文档
CodeCov
CodeFactor

快速入门

使用该库

1. 运行 pip install flood-forecast
2. 关于训练模型的详细信息可在 Wiki 中找到。
3. 请查看我们的 Confluence 文档

当前支持的模型

1. 原生 LSTM (LSTM)：一种基础 LSTM，适用于多变量时间序列预测和迁移学习。
2. 完整 Transformer (model_dict 中的 SimpleTransformer)：包含全部 8 个编码器和解码器层的原始完整 Transformer。推理时需要输入目标值。
3. 简单多头注意力机制 (MultiHeadSimple)：一个简单的多头注意力模块和线性嵌入层。适合迁移学习。
4. 带线性解码器的 Transformer (model_dict 中的 CustomTransformerDecoder)：具有 n 个编码器层（可调）和线性解码器的 Transformer。适用于预测、分类或异常检测。
5. DA-RNN：（DARNN）一种综合性能良好的模型，结合了 LSTM 和注意力机制。
6. 增强时间序列预测中 Transformer 的局部性和突破内存瓶颈（在 model_dict 中称为 DecoderTransformer）：
7. Transformer XL：将 Transformer XL 移植应用于时间序列。
8. Informer：超越高效 Transformer 的长序列时间序列预测（Informer）
9. DeepAR
10. DSANet：来自 DSANet 论文的模型，带有额外的可选参数。
11. 简单线性模型 (SimpleLinearModel)：本质上是一个增加了几层的线性回归模型。非常适合快速原型化功能和可解释性分析。
12. 原生 GRU，可选概率输出层。适用于多变量时间序列预测和分类。
13. 来自 AAAI 论文 Transformer 是否适用于时间序列预测 的 DLinear 和 NLinear。
14. Crossformer 来自 ICLR 2023
15. 异常检测 Transformer
16. TSMixer
17. 倒置 Transformer + 各种注意力机制

即将发布的模型

我们计划在近期发布多个新模型。请查看我们的项目看板以获取更多信息

集成

Google Cloud Platform

Weights and Biases

贡献

有关贡献的说明，请参阅我们的 贡献页面 和 项目看板。

历史河流流量数据

任务 1 流量预测

本任务专注于根据当前流量、温度和降水等因素，预测河流未来的流量或水位（分别以 cfs 或英尺为单位）。未来我们计划添加更多有助于河流流量预测的变量，例如积雪数据和周围土壤湿度指数。

任务 2 洪水严重程度预测

任务二则侧重于根据洪水预报、人口信息和地形特征来预测洪水的严重程度。洪水严重程度由伤亡人数、财产损失和农作物损害等多个因素决定。

如果您使用本仓库中的数据或代码，请引用以下文献。此外，请同时引用各模型的原始作者。

@misc{godfried2020flowdb,
      title={FlowDB 大规模降水、河流和山洪数据集},
      author={Isaac Godfried、Kriti Mahajan、Maggie Wang、Kevin Li 和 Pranjalya Tiwari},
      year={2020},
      eprint={2012.11154},
      archivePrefix={arXiv},
      primaryClass={cs.AI}
}

Flow-Forecast 快速上手指南

Flow-Forecast 是一个专注于时间序列预测、分类和异常检测的开源深度学习框架。它集成了 Transformer、LSTM、GRU、ODE 等前沿模型，并提供可解释性指标及云端部署支持。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows
• Python 版本：推荐 Python 3.7 及以上版本
• 前置依赖：
  • pip (Python 包管理工具)
  • git (用于克隆代码库，如需查看源码)
  • 建议创建独立的虚拟环境 (如 venv 或 conda) 以避免依赖冲突。

安装步骤

您可以直接通过 PyPI 安装稳定版。国内开发者建议使用清华或阿里镜像源以加速下载。

使用默认源安装：

pip install flood-forecast

使用国内镜像源加速安装（推荐）：

pip install flood-forecast -i https://pypi.tuna.tsinghua.edu.cn/simple

注意：包名为 flood-forecast，尽管项目仓库名为 flow-forecast。

基本使用

安装完成后，您可以立即在 Python 项目中导入并使用该库。Flow-Forecast 的核心功能包括模型训练、推理以及利用内置的多种 SOTA 模型（如 Transformer, LSTM, Informer 等）。

1. 导入库与验证安装

在最简单的场景中，首先验证库是否可用：

import flood_forecast as ff

print(f"Flow-Forecast version: {ff.__version__}")

2. 配置与训练模型

Flow-Forecast 采用配置文件（通常为 JSON 或 YAML）来定义模型架构、数据路径和超参数。以下是一个基于 Python 代码启动训练流程的最小化示例逻辑：

from flood_forecast.trainer import train_function

# 定义配置文件路径 (需预先准备好包含数据路径、模型类型等信息的 config 文件)
config_path = "path/to/your/config.json"

# 启动训练
# 支持的模型包括：LSTM, SimpleTransformer, MultiHeadSimple, Informer, DeepAR 等
train_function(config_path)

3. 选择模型

在配置文件中，您可以通过 model_name 参数指定要使用的模型。目前支持的热门模型包括：

• LSTM: 基础 LSTM，适用于多变量预测。
• SimpleTransformer: 完整的 Transformer 架构。
• Informer: 适用于长序列时间序列预测的高效 Transformer。
• DeepAR: 概率预测模型。
• DLinear / NLinear: 高效的线性模型基线。
• AnomalyTransformer: 专用于异常检测。

下一步建议： 详细的模型参数配置、数据预处理格式以及特定任务的教程，请参考官方 Wiki 文档 或 Tutorials 仓库。