---

LibCity（阡陌）

主页 | 文档 | 数据集 | 会议论文 | 完整论文 | 论文列表 | 实验工具 | EA&B赛道论文 | 中文版

LibCity是一个统一、全面且可扩展的库，为交通预测领域的研究人员提供可靠的实验工具和便捷的开发框架。我们的库基于PyTorch实现，将与交通预测相关的所有必要步骤或组件整合进一个系统化的流程中，使研究人员能够开展全面的实验。LibCity将有助于推动交通预测领域的标准化和可重复性研究。

LibCity目前支持以下任务：

• 交通状态预测
  • 交通流量预测
  • 交通速度预测
  • 按需服务预测
  • 起讫点矩阵预测
  • 交通事故预测
• 轨迹下一位置预测
• 预计到达时间
• 地图匹配
• 道路网络表示学习

特性

• 统一：LibCity构建了一个系统化的流程，用于在统一的平台上实现、使用和评估交通预测模型。我们设计了基础的时空数据存储方式、统一的模型实例化接口以及标准化的评估流程。

• 全面：我们复现了涵盖9项交通预测任务的74种模型，形成了一个全面的模型库。同时，LibCity收集了来自不同来源的52个常用数据集，并实现了多种常用的评估指标和策略，用于性能评估。

• 可扩展：LibCity采用模块化设计，允许用户灵活地将自定义组件插入到库中。因此，新研究人员可以在LibCity的支持下轻松开发新的模型。

LibCity 新闻

2024年4月12日：我们发布了 M-LibCity v0.1，即 LibCity 的 MindSpore 版本。该初始版本支持九项交通预测任务，包括交通状态预测、轨迹下一跳预测以及预计到达时间等。此外，M-LibCity 还支持在 GPU 和 NPU 等多种后端上的多卡并行加速。更多详细信息及附加资源，请访问此 链接。

2023年4月11日：基于 LibCity 的创意设计 ZongHeng 在第九届中国研究生智慧城市技术与创意设计大赛中荣获一等奖！微信

2023年8月24日： 我们发表了一篇题为《面向城市时空预测的统一数据管理与综合性能评估【实验、分析与基准测试】》的论文，内容包括：(1) 城市时空数据的统一存储格式；(2) 城市时空预测模型的技术发展路线图；(3) 使用 18 种模型和 20 个数据集进行的大规模实验与性能评估。[论文]。

2023年6月20日： 我们发布了 2015 年 11 月采集的北京轨迹数据集，包含 1018312 条轨迹。我们从 OpenStreetMap 获取了相应的路网数据，并对轨迹数据进行了预处理，得到了与路网匹配的北京轨迹数据集。我们认为该数据集将有助于推动城市轨迹挖掘相关研究的发展。请通过此 链接 获取，并请务必确保该数据仅用于 科研目的。

2023年6月4日：LibCity 在第三届中国科学开源软件创意大赛中荣获二等奖！微信

2023年4月27日： 我们发表了一篇题为《LibCity：迈向高效全面的城市时空预测的统一库》的完整论文（arXiv 链接），其中提供了关于 LibCity 的更多细节。[论文]。

2022年11月19日：我们在 LibCity 上开发的基于自注意力机制的交通流量预测模型 PDFormer 被 AAAI2023 接收，更多详情请参阅此 链接。

2022年8月5日：我们为 LibCity 开发了一个 实验管理工具，允许用户通过可视化界面完成实验。代码仓库链接在此：这里。部分介绍（中文）：微信，知乎。

2022年4月27日：我们发布了 LibCity 的首个版本 v0.3，这是最新版本，支持 9 类时空预测任务，涵盖 60 多种预测模型和近 40 个城市时空数据集。

2021年11月24日：我们在知乎上发布了一些入门教程（中文），链接1，链接2，链接3，链接4，链接5，链接6……

2021年11月10日：我们提供了一份文档，详细介绍了 LibCity 定义的 原子文件 格式。您可以在此下载 英文版 和 中文版 以获取更多详情。

2021年11月7日：我们在 ACM SIGSPATIAL 2021 本地赛道上做了一场关于 LibCity 的演示。您可以在此下载 LibCity 演示文稿（中文） 和 LibCity 中文教程。

2021年11月7日：我们在 ACM SIGSPATIAL 2021 主赛道上也做了一场关于 LibCity 的演示。以下是 演示视频（英文） 和 演示文稿（英文）。

整体框架

• 配置模块：负责管理框架中涉及的所有参数。
• 数据模块：负责加载数据集及进行数据预处理操作。
• 模型模块：负责初始化复现的基线模型或自定义模型。
• 评估模块：负责通过多个指标评估模型的预测结果。
• 执行模块：负责模型的训练和预测。

安装

LibCity 只能通过源代码安装。

请执行以下命令以获取源代码：

git clone https://github.com/LibCity/Bigscity-LibCity
cd Bigscity-LibCity

有关环境配置的更多详细信息，请参阅 文档。

快速入门

在 LibCity 中运行模型之前，请确保您已下载至少一个数据集，并将其放置在 ./raw_data/ 目录下。数据集的下载链接为：百度网盘，提取码 1231 或 Google Drive。LibCity 中使用的所有数据集都需要被处理成 原子文件 格式。

脚本 run_model.py 用于在 LibCity 中训练和评估单个模型。运行 run_model.py 时，必须指定以下三个参数：task、dataset 和 model。

例如：

python run_model.py --task traffic_state_pred --model GRU --dataset METR_LA

该脚本将以默认配置在 METR_LA 数据集上运行 GRU 模型，进行交通状态预测任务。我们已在 这里 发布了数据集、模型与任务之间的对应关系。 更多详细信息请参阅 文档。

TensorBoard 可视化

在模型训练过程中，LibCity 会记录每个 epoch 的损失，并支持 TensorBoard 可视化。

模型运行一次后，您可以使用以下命令进行可视化：

tensorboard --logdir 'libcity/cache'

TensorFlow 安装未找到 - 正在以功能受限模式运行。
TensorBoard 正在 localhost 上提供服务；如需对外公开，请使用代理或传递 --bind_all 参数。
TensorBoard 2.4.1 已启动，地址为 http://localhost:6006/（按 CTRL+C 即可退出）。

请在浏览器中访问此地址 (http://localhost:6006/) 查看可视化结果。

复现模型列表

有关 LibCity 中所有复现模型的列表，请参阅 文档，您可以在其中查看模型的缩写及其对应的论文和引用信息。

教程

为了方便用户使用 LibCity，我们提供了一些教程：

• 我们曾在 ACM SIGSPATIAL 2021 主会场和本地分会场发表讲座。相关讲座视频和幻灯片请参见我们的 主页（中文和英文版本）。
• 我们在文档中提供了入门级教程（中文和英文版本）：
  • 安装与快速入门 & 安装和快速上手
  • 在 LibCity 中运行现有模型 & 运行LibCity中已复现的模型
  • 向 LibCity 添加新模型 & 在LibCity中添加新模型
  • 使用自动化工具调参 & 使用自动化工具调参
  • 原子文件可视化 & 原子文件可视化
• 为了方便中国国内用户使用，我们在知乎上提供了入门教程（中文版本）：
  • LibCity：一个统一、全面、可扩展的交通预测算法库
  • LibCity入门教程（1）——安装与快速上手
  • LibCity入门教程（2）——运行LibCity中已复现的模型
  • LibCity入门教程（3）——在LibCity中添加新模型
  • LibCity入门教程（4）—— 自动化调参工具
  • 北航BIGSCity课题组提出LibCity工具库：城市时空预测深度学习开源平台

贡献

LibCity 主要由北京航空航天大学智慧城市兴趣小组（BIGSCITY）开发和维护。该库的核心开发者是 @aptx1231 和 @WenMellors。

此外，还有多位共同开发者参与了模型的复现工作，其贡献名单详见 复现贡献列表。

如果您遇到任何 bug 或有任何建议，请通过 提交 issue 与我们联系。您也可以发送邮件至 bigscity@126.com 与我们取得联系。

引用

我们的论文已被 ACM SIGSPATIAL 2021 接受。如果您发现 LibCity 对您的研究或开发有所帮助，请引用我们的 论文。

@inproceedings{libcity,
  author = {Wang, Jingyuan and Jiang, Jiawei and Jiang, Wenjun and Li, Chao and Zhao, Wayne Xin},
  title = {LibCity: An Open Library for Traffic Prediction},
  year = {2021},
  isbn = {9781450386647},
  publisher = {Association for Computing Machinery},
  address = {New York, NY, USA},
  url = {https://doi.org/10.1145/3474717.3483923},
  doi = {10.1145/3474717.3483923},
  booktitle = {Proceedings of the 29th International Conference on Advances in Geographic Information Systems},
  pages = {145–148},
  numpages = {4},
  keywords = {时空系统, 可复现性, 交通预测},
  location = {北京, 中国},
  series = {SIGSPATIAL '21}
}

对于长文，请按如下方式引用：

@article{libcitylong,
  title={LibCity: A Unified Library Towards Efficient and Comprehensive Urban Spatial-Temporal Prediction}, 
  author={Jiang, Jiawei and Han, Chengkai and Jiang, Wenjun and Zhao, Wayne Xin and Wang, Jingyuan},
  journal={arXiv preprint arXiv:2304.14343},
  year={2023}
}

许可证

LibCity 采用 Apache License 2.0 许可协议。

星标用户

分叉用户

Bigscity-LibCity 快速上手指南

LibCity（阡陌）是一个统一、综合且可扩展的交通预测开源库，基于 PyTorch 构建。它涵盖了从数据处理、模型构建到评估的完整流程，支持交通状态预测、轨迹预测、到达时间估计等 9 大类任务，复现了 70+ 种经典模型。

环境准备

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

• 操作系统: Linux 或 macOS (Windows 需配置相应环境)
• Python: 3.7 或更高版本
• 深度学习框架: PyTorch 1.7.1 或更高版本
• 其他依赖: Git, TensorBoard (用于可视化)

建议创建独立的虚拟环境以避免依赖冲突：

python -m venv libcity_env
source libcity_env/bin/activate  # Windows 用户使用: libcity_env\Scripts\activate

安装步骤

LibCity 目前仅支持源码安装。请执行以下命令克隆仓库并进入目录：

git clone https://github.com/LibCity/Bigscity-LibCity
cd Bigscity-LibCity

注意：具体的 Python 依赖包安装请参考官方文档中的 requirements.txt 或通过 pip 安装相关依赖。如需详细的环境配置说明，请访问 安装文档。

基本使用

1. 准备数据

运行模型前，必须至少下载一个数据集并将其放置在 ./raw_data/ 目录下。LibCity 要求所有数据必须处理为标准的 Atomic Files 格式。

• 下载地址:
  • 百度网盘 (提取码: 1231): 点击跳转
  • Google Drive: 点击跳转
• 数据格式详情: Atomic Files 规范
• 任务 - 模型 - 数据集对应表: 查看对应关系

2. 运行模型

使用 run_model.py 脚本即可启动训练和评估。运行时必须指定三个核心参数：任务类型 (--task)、模型名称 (--model) 和 数据集名称 (--dataset)。

示例命令： 以下命令将在 METR_LA 数据集上，使用 GRU 模型进行交通状态预测任务（使用默认配置）：

python run_model.py --task traffic_state_pred --model GRU --dataset METR_LA

3. 结果可视化

LibCity 在训练过程中会自动记录每个 epoch 的 loss，并支持通过 TensorBoard 进行可视化。

训练完成后，执行以下命令启动可视化服务：

tensorboard --logdir 'libcity/cache'

终端输出类似如下信息：

TensorFlow installation not found - running with reduced feature set.
Serving TensorBoard on localhost; to expose to the network, use a proxy or pass --bind_all
TensorBoard 2.4.1 at http://localhost:6006/ (Press CTRL+C to quit)

在浏览器中访问 http://localhost:6006/ 即可查看训练曲线和评估结果。

---

更多详细信息、完整模型列表及高级定制开发指南，请参阅 LibCity 官方文档。