EasyTPP [ICLR 2024]

EasyTPP is an easy-to-use development and application toolkit for Temporal Point Process (TPP), with key features in configurability, compatibility and reproducibility. We hope this project could benefit both researchers and practitioners with the goal of easily customized development and open benchmarking in TPP.

| Features | Model List | Dataset | Quick Start | Benchmark |Documentation |Todo List | Citation |Acknowledgement | Star History |

News

• [02-17-2024] EasyTPP supports HuggingFace dataset API: all datasets have been published in HuggingFace Repo and see tutorial notebook for an example of usage.
• [01-16-2024] Our paper EasyTPP: Towards Open Benchmarking Temporal Point Process is accepted by ICLR'2024!
• [09-30-2023] We published two textual event sequence datasets GDELT and Amazon-text-review that are used in our paper LAMP, where LLM can be applied for event prediction! See Documentation for more details.
• [09-30-2023] Two of our papers Language Model Can Improve Event Prediction by Few-Shot Abductive Reasoning (LAMP) and Prompt-augmented Temporal Point Process for Streaming Event Sequence (PromptTPP) are accepted by NeurIPS'2023!

Click to see previous news

• [09-02-2023] We published two non-anthropogenic datasets earthquake and volcano eruption! See Dataset for details.
• [05-29-2023] We released EasyTPP v0.0.1!
• [12-27-2022] Our paper Bellman Meets Hawkes: Model-Based Reinforcement Learning via Temporal Point Processes was accepted by AAAI'2023!
• [10-01-2022] Our paper HYPRO: A Hybridly Normalized Probabilistic Model for Long-Horizon Prediction of Event Sequences was accepted by NeurIPS'2022!
• [05-01-2022] We started to develop EasyTPP.

Features [Back to Top]

• Configurable and customizable: models are modularized and configurable，with abstract classes to support developing customized TPP models.
• PyTorch-based implementation: EasyTPP implements state-of-the-art TPP models using PyTorch 1.7.0+, providing a clean and modern deep learning framework.
• Reproducible: all the benchmarks can be easily reproduced.
• Hyper-parameter optimization: a pipeline of optuna-based HPO is provided.

Model List [Back to Top]

We provide reference implementations of various state-of-the-art TPP papers:

Dataset [Back to Top]

We preprocessed one synthetic and five real world datasets from widely-cited works that contain diverse characteristics in terms of their application domains and temporal statistics: - Synthetic: a univariate Hawkes process simulated by Tick library. - Retweet (Zhou, 2013): timestamped user retweet events. - Taxi (Whong, 2014): timestamped taxi pick-up events. - StackOverflow (Leskovec, 2014): timestamped user badge reward events in StackOverflow. - Taobao (Xue et al, 2022): timestamped user online shopping behavior events in Taobao platform. - Amazon (Xue et al, 2022): timestamped user online shopping behavior events in Amazon platform.

Per users' request, we processed two non-anthropogenic datasets - Earthquake: timestamped earthquake events over the Conterminous U.S from 1996 to 2023, processed from USGS. - Volcano eruption: timestamped volcano eruption events over the world in recent hundreds of years, processed from The Smithsonian Institution.

All datasets are preprocess to the Gatech format dataset widely used for TPP researchers, and saved at Google Drive with a public access.

Quick Start [Back to Top]

Colab Tutorials

Explore the following tutorials that can be opened directly in Google Colab:

• Tutorial 1: Dataset in EasyTPP.
• Tutorial 2: Tensorboard in EasyTPP.
• Tutorial 3: Training and Evaluation of TPPs.

End-to-end Example

We provide an end-to-end example for users to run a standard TPP model with EasyTPP.

Step 1. Installation

First of all, we can install the package either by using pip or from the source code on Github.

To install the latest stable version:

pip install easy-tpp

To install the latest on GitHub:

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

Step 2. Prepare datasets

We need to put the datasets in a local directory before running a model and the datasets should follow a certain format. See OnlineDoc - Datasets for more details.

Suppose we use the taxi dataset in the example.

Step 3. Train the model

Before start training, we need to set up the config file for the pipeline. We provide a preset config file in Example Config. The details of the configuration can be found in OnlineDoc - Training Pipeline.

After the setup of data and config, the directory structure is as follows:

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

    configs
     |______experiment_config.yaml

Then we start the training by simply running the script

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='Dir of configuration yaml to train and evaluate the model.')

    parser.add_argument('--experiment_id', type=str, required=False, default='NHP_train',
                        help='Experiment id in the config file.')

    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 more detailed example can be found at OnlineDoc - QuickStart.

Documentation [Back to Top]

The classes and methods of EasyTPP have been well documented so that users can generate the documentation by:

```shell cd doc pip install -r requ