EasyTPP [ICLR 2024]

EasyTPP是一个易于使用的时间点过程（TPP）开发和应用工具包，其主要特点在于可配置性、兼容性和可复现性。我们希望这个项目能够为研究人员和实践者带来益处，目标是在TPP领域实现易于定制的开发和开放的基准测试。 <span id='top'/>

新闻

<span id='news'/> - ![新](https://yellow-cdn.veclightyear.com/0a4dffa0/5cddb04b-016b-487d-9697-9e50ee841561.png) [2024-02-17] EasyTPP 支持 HuggingFace 数据集 API：所有数据集已发布在 [HuggingFace 仓库](https://huggingface.co/easytpp)，使用示例请参见[教程笔记本](https://github.com/ant-research/EasyTemporalPointProcess/blob/main/notebooks/easytpp_1_dataset.ipynb)。 - ![新](https://yellow-cdn.veclightyear.com/0a4dffa0/5cddb04b-016b-487d-9697-9e50ee841561.png) [2024-01-16] 我们的论文 [EasyTPP: 面向时间点过程的开放基准测试](https://arxiv.org/abs/2307.08097) 被 ICLR'2024 接收！ - ![新](https://yellow-cdn.veclightyear.com/0a4dffa0/5cddb04b-016b-487d-9697-9e50ee841561.png) [2023-09-30] 我们发布了两个文本事件序列数据集 [GDELT](https://drive.google.com/drive/folders/1Ms-ATMMFf6v4eesfJndyuPLGtX58fCnk) 和 [Amazon-text-review](https://drive.google.com/drive/folders/1-SLYyrl7ucEG7NpSIF0eSoG9zcbZagZw)，这些数据集在我们的论文 [LAMP](https://arxiv.org/abs/2305.16646) 中使用，可以应用大语言模型进行事件预测！更多详情请参见[文档](https://ant-research.github.io/EasyTemporalPointProcess/user_guide/dataset.html#preprocessed-datasets)。 - ![新](https://yellow-cdn.veclightyear.com/0a4dffa0/5cddb04b-016b-487d-9697-9e50ee841561.png) [2023-09-30] 我们的两篇论文 [语言模型可通过少样本溯因推理改进事件预测](https://arxiv.org/abs/2305.16646)（LAMP）和 [基于提示的时间点过程用于流式事件序列](https://arxiv.org/abs/2310.04993)（PromptTPP）被 NeurIPS'2023 接收！ <details> <summary>点击查看往期新闻</summary> <p> - [2023-09-02] 我们发布了两个非人为数据集 [地震](https://drive.google.com/drive/folders/1ubeIz_CCNjHyuu6-XXD0T-gdOLm12rf4) 和 [火山喷发](https://drive.google.com/drive/folders/1KSWbNi8LUwC-dxz1T5sOnd9zwAot95Tp?usp=drive_link)！详情请参见<a href='#dataset'>数据集</a>。 - [2023-05-29] 我们发布了 ``EasyTPP`` v0.0.1！ - [2022-12-27] 我们的论文 [Bellman 遇上 Hawkes：基于时间点过程的模型化强化学习](https://arxiv.org/abs/2201.12569) 被 AAAI'2023 接收！ - [2022-10-01] 我们的论文 [HYPRO：用于长期事件序列预测的混合归一化概率模型](https://arxiv.org/abs/2210.01753) 被 NeurIPS'2022 接收！ - [2022-05-01] 我们开始开发 `EasyTPP`。</p> </details>

特性 <a href='#top'>[返回顶部]</a>

可配置和可自定义：模型模块化且可配置，提供抽象类以支持开发自定义 TPP 模型。
同时兼容 Tensorflow 和 PyTorch 框架：EasyTPP 实现了两套等效的模型，可分别在 Tensorflow（包括 Tensorflow 1.13.1 和 Tensorflow 2.0）和 PyTorch 1.7.0+ 下运行。虽然 PyTorch 模型在研究人员中更受欢迎，但与 Tensorflow 的兼容性对工业实践者来说很重要。
可重现：所有基准测试都可以轻松重现。
超参数优化：提供基于 optuna 的 HPO 流程。

模型列表 <a href='#top'>[返回顶部]</a>

我们提供了各种最先进的 TPP 论文的参考实现：

序号	发表会议	模型	论文	实现
1	KDD'16	RMTPP	循环标记时间点过程：将事件历史嵌入向量	[Tensorflow](https://github.com/ant-research/EasyTemporalPointProcess/blob/main/easy_tpp/model/tf_model/tf_rmtpp.py<br/>[Torch](https://github.com/ant-research/EasyTemporalPointProcess/blob/main/easy_tpp/model/torch_model/torch_rmtpp.py
2	NeurIPS'17	NHP	神经霍克斯过程：神经自调制多变量点过程	[Tensorflow](https://github.com/ant-research/EasyTemporalPointProcess/blob/main/easy_tpp/model/tf_model/tf_nhp.py<br/>[Torch](https://github.com/ant-research/EasyTemporalPointProcess/blob/main/easy_tpp/model/torch_model/torch_nhp.py
3	NeurIPS'19	FullyNN	基于全神经网络的通用时间点过程模型	[Tensorflow](https://github.com/ant-research/EasyTemporalPointProcess/blob/main/easy_tpp/model/tf_model/tf_fullnn.py<br/>[Torch](https://github.com/ant-research/EasyTemporalPointProcess/blob/main/easy_tpp/model/torch_model/torch_fullynn.py
4	ICML'20	SAHP	自注意力霍克斯过程	[Tensorflow](https://github.com/ant-research/EasyTemporalPointProcess/blob/main/easy_tpp/model/tf_model/tf_sahp.py<br/>[Torch](https://github.com/ant-research/EasyTemporalPointProcess/blob/main/easy_tpp/model/torch_model/torch_sahp.py
5	ICML'20	THP	Transformer霍克斯过程	[Tensorflow](https://github.com/ant-research/EasyTemporalPointProcess/blob/main/easy_tpp/model/tf_model/tf_thp.py<br/>[Torch](https://github.com/ant-research/EasyTemporalPointProcess/blob/main/easy_tpp/model/torch_model/torch_thp.py
6	ICLR'20	IntensityFree	无强度学习时间点过程	[Tensorflow](https://github.com/ant-research/EasyTemporalPointProcess/blob/main/easy_tpp/model/tf_model/tf_intensity_free.py<br/>[Torch](https://github.com/ant-research/EasyTemporalPointProcess/blob/main/easy_tpp/model/torch_model/torch_intensity_free.py
7	ICLR'21	ODETPP	神经时空点过程（简化版）	[Tensorflow](https://github.com/ant-research/EasyTemporalPointProcess/blob/main/easy_tpp/model/tf_model/tf_ode_tpp.py<br/>[Torch](https://github.com/ant-research/EasyTemporalPointProcess/blob/main/easy_tpp/model/torch_model/torch_ode_tpp.py
8	ICLR'22	AttNHP	不规则间隔事件及其参与者的Transformer嵌入	[Tensorflow](https://github.com/ant-research/EasyTemporalPointProcess/blob/main/easy_tpp/model/tf_model/tf_attnhp.py<br/>[Torch](https://github.com/ant-research/EasyTemporalPointProcess/blob/main/easy_tpp/model/torch_model/torch_attnhp.py

数据集 <a href='#top'>[返回顶部]</a>

<span id='dataset'/> 我们预处理了一个合成数据集和五个来自广泛引用的研究的真实世界数据集，这些数据集在应用领域和时间统计特性方面具有多样性：

合成数据：使用Tick库模拟的单变量Hawkes过程。
Retweet（Zhou, 2013）：带时间戳的用户转发事件。
出租车（Whong, 2014）：带时间戳的出租车接客事件。
StackOverflow（Leskovec, 2014）：StackOverflow中带时间戳的用户徽章奖励事件。
淘宝（Xue et al, 2022）：淘宝平台上带时间戳的用户在线购物行为事件。
亚马逊（Xue et al, 2022）：亚马逊平台上带时间戳的用户在线购物行为事件。

应用户要求，我们还处理了两个非人为数据集：

地震：1996年至2023年美国本土地区带时间戳的地震事件，数据来源于USGS。
火山喷发：近几百年来全球带时间戳的火山喷发事件，数据来源于史密森学会。

所有数据集都被预处理成TPP研究者广泛使用的Gatech格式，并保存在Google Drive中，可公开访问。

快速开始 <a href='#top'>[返回顶部]</a>

我们为用户提供了一个端到端的示例，用于使用EasyTPP运行标准TPP模型。

步骤1. 安装

首先，我们可以通过pip或从Github上的源代码安装软件包。

安装最新稳定版本：

pip install easy-tpp

从GitHub安装最新版本：

git clone https://github.com/ant-research/EasyTemporalPointProcess.git
cd EasyTemporalPointProcess
python setup.py install

步骤2. 准备数据集

在运行模型之前，我们需要将数据集放在本地目录中，且数据集应遵循特定格式。详情请参见在线文档 - 数据集。

假设我们在示例中使用出租车数据集。

步骤3. 训练模型

开始训练之前，我们需要为流程设置配置文件。我们在示例配置中提供了一个预设配置文件。配置详情可在在线文档 - 训练流程中找到。

完成数据和配置设置后，目录结构如下：

    data
     |______taxi
             |____ train.pkl
             |____ dev.pkl
             |____ test.pkl

    configs
     |______experiment_config.yaml

然后，我们只需运行以下脚本即可开始训练：

import argparse
from easy_tpp.config_factory import Config
from easy_tpp.runner import Runner

def main():
    parser = argparse.ArgumentParser()

    parser.add_argument('--config_dir', type=str, required=False, default='configs/experiment_config.yaml',
                        help='训练和评估模型的配置yaml文件目录。')

    parser.add_argument('--experiment_id', type=str, required=False, default='NHP_train',
                        help='配置文件中的实验ID。')

    args = parser.parse_args()

    config = Config.build_from_yaml_file(args.config_dir, experiment_id=args.experiment_id)

    model_runner = Runner.build_from_config(config)

    model_runner.run()

if __name__ == '__main__':
    main()

更详细的示例可以在在线文档 - 快速开始中找到。

文档 <a href='#top'>[返回顶部]</a>

EasyTPP的类和方法已经有了详细的文档说明，用户可以通过以下方式生成文档：

cd doc
pip install -r requirements.txt
make html

注意：

doc/requirements.txt仅用于Sphinx生成文档，可由Github actions .github/workflows/docs.yml自动生成。（由拉取请求触发。）

完整文档可在网站上查阅。

基准测试 <a href='#top'>[返回顶部]</a>

<span id='benchmark'/> 在 [examples](https://github.com/ant-research/EasyTemporalPointProcess/tree/main/examples) 文件夹中，我们提供了一个[脚本](https://github.com/ant-research/EasyTemporalPointProcess/blob/main/examples/benchmark_script.py)来对TPPs进行基准测试，使用Taxi数据集作为输入。

要运行该脚本，您需要按照上述说明下载Taxi数据。配置文件已经设置好了。然后运行：

cd examples
python benchmark_script.py

许可证 <a href='#top'>[返回顶部]</a>

本项目采用 Apache License (Version 2.0) 许可。此工具包还包含一些根据其他开源许可证修改的代码。更多信息请参见 NOTICE 文件。

待办事项 <a href='#top'>[返回顶部]</a>

新数据集：
- 地震：源数据可在 USGS 获取。
- 火山喷发：源数据可在 NCEI 获取。
新模型：
- Meta Temporal Point Process，ICLR 2023。
- 基于TPP的模型based RL，AAAI 2022。

引用 <a href='#top'>[返回顶部]</a>

如果您发现EasyTPP对您的研究或开发有用，请引用以下<a href="https://arxiv.org/abs/2307.08097" target="_blank">论文</a>：

@inproceedings{xue2024easytpp,
      title={EasyTPP: Towards Open Benchmarking Temporal Point Processes}, 
      author={Siqiao Xue and Xiaoming Shi and Zhixuan Chu and Yan Wang and Hongyan Hao and Fan Zhou and Caigao Jiang and Chen Pan and James Y. Zhang and Qingsong Wen and Jun Zhou and Hongyuan Mei},
      booktitle = {International Conference on Learning Representations (ICLR)},
      year = {2024},
      url ={https://arxiv.org/abs/2307.08097}
}