py-tgb 2.3.0

Temporal Graph Benchmark project repo

Temporal Graph Benchmark for Machine Learning on Temporal Graphs (NeurIPS 2023 Datasets and Benchmarks Track)

TGB 2.0: A Benchmark for Learning on Temporal Knowledge Graphs and Heterogeneous Graphs (NeurIPS 2024 Datasets and Benchmarks Track)

Overview of the Temporal Graph Benchmark (TGB) pipeline:

• TGB includes large-scale and realistic datasets from 10 different domains with both dynamic link prediction and node property prediction tasks.
• TGB automatically downloads datasets and processes them into numpy, PyTorch and PyG compatible TemporalData formats.
• Novel TG models can be easily evaluated on TGB datasets via reproducible and realistic evaluation protocols.
• TGB provides public and online leaderboards to track recent developments in temporal graph learning domain.
• Now TGB supports temporal homogeneous graphs, temporal knowledge graphs and temporal heterogenenous graph datasets.

To submit to TGB leaderboard, please fill in this google form

See all version differences and update notes here

Announcements

Excited to announce TGB 2.0, has been presented at NeurIPS 2024 Datasets and Benchmarks Track

See our camera ready version and arXiv version for details. Please install locally first. We welcome your feedback and suggestions.

Excited to announce TGX, a companion package for analyzing temporal graphs in WSDM 2024 Demo Track

TGX supports all TGB datasets and provides numerous temporal graph visualization plots and statistics out of the box. See our paper: Temporal Graph Analysis with TGX and TGX website.

Datasets have migrated to new network storage (Arbutus / Alliance Canada). Download links from versions prior to 2.3.0 are now deprecated and will no longer work — please update to version 2.3.0 or later to continue downloading datasets.

Please update to version 2.3.0

version 2.3.0

Datasets migrated to new network storage (Arbutus / Alliance Canada); download links updated in tgb/utils/info.py. Download links from versions prior to 2.3.0 are deprecated, please update. Added a full unit test suite and CI workflow covering download, preprocessing, negative sampling, evaluation, and info utilities. Made torch/PyG an optional dependency guarded at import time, so core TGB functionality works without torch installed.

version 2.2.0

Adding license for TGB software (for dataset license please check TGB website). Printing messages now will not automatically set to stdout, use TGB_VERBOSE=True in your shell to set the print to be verbose. Default option is to automatically download the datasets (rather than command line input as before).

version 2.1.0

Includes supplementary datasets tgbl-lastfm tgbl-enron tgbl-uci tgbl-subreddit for research purposes. For more details, see the release notes

version 2.0.0

Includes all new datasets from TGB 2.0 including temporal knowledge graphs and temporal heterogeneous graphs.

-->

Pip Install

You can install TGB via pip. Requires python >= 3.9

pip install py-tgb

By default this is a pure Python/numpy install — PyTorch and PyG are not required and are not pulled in. This is enough for dataset loading (LinkPropPredDataset/NodePropPredDataset) and evaluation (Evaluator, NegativeEdgeSampler) with plain numpy arrays.

If you want to use the PyG dataset wrappers (PyGLinkPropPredDataset/PyGNodePropPredDataset) or run the example model scripts, install the torch extra, which pulls in torch-geometric:

pip install py-tgb[torch]

torch-geometric doesn't pin a specific PyTorch build, so install the PyTorch build matching your platform/CUDA first if you need a non-default one, e.g.:

pip install torch          # CPU (macOS / no CUDA)
# or a CUDA build, e.g.:  pip install torch --index-url https://download.pytorch.org/whl/cu121
pip install py-tgb[torch]

Development Install (uv, optional)

For contributing to TGB, uv provides a fast, reproducible environment. This is a developer/CI convenience only — it does not change how the package is built or how pip install py-tgb behaves for users.

# install uv: https://docs.astral.sh/uv/getting-started/installation/
uv venv --python 3.11 && source .venv/bin/activate

uv pip install -e .                     # builds via poetry-core, installs runtime deps (pure numpy, no torch)
uv pip install -r requirements-dev.txt  # pytest, mkdocs, ...

# Only needed for the PyG dataset wrappers / example scripts:
uv pip install torch                    # CPU (macOS / no CUDA)
# CUDA example: uv pip install torch==2.0.0 --index-url https://download.pytorch.org/whl/cu117
uv pip install -e ".[torch]"            # installs torch-geometric

Testing

TGB ships an offline-by-default pytest suite that guards dataset metadata (URLs/versions in tgb/utils/info.py), the download logic, and core utilities.

pip install -r requirements-dev.txt   # pytest, pytest-mock
pip install -e .                       # runtime deps (pure numpy, no torch required)

pytest -m "not network"     # fast, offline suite (default for CI)
pytest --run-network        # also check that each dataset URL is reachable

Nearly all tests run with no torch installed at all — tgb/utils/utils.py, Evaluator, NegativeEdgeSampler, and the dataset classes all guard their torch imports and fall back to plain numpy behavior. test/test_no_torch.py simulates torch being uninstalled and asserts this directly, including that the PyG-only wrapper modules (which do require pip install py-tgb[torch]) still fail with a clear ImportError rather than silently misbehaving. Only a handful of tests that construct actual tensors (e.g. test_eval_torch_matches_numpy) skip when torch isn't installed. See test/README.md for the full layout and the network-test opt-in.

Links and Datasets

The project website can be found here.

The API documentations can be found here.

all dataset download links can be found at info.py

TGB dataloader will also automatically download the dataset as well as the negative samples for the link property prediction datasets.

if website is unaccessible, please use this link instead.

Running Example Methods

• For the dynamic link property prediction task, see the examples/linkproppred folder for example scripts to run TGN, DyRep and EdgeBank on TGB datasets.
• For the dynamic node property prediction task, see the examples/nodeproppred folder for example scripts to run TGN, DyRep and EdgeBank on TGB datasets.
• For all other baselines, please see the TGB_Baselines repo.

Acknowledgments

We thank the OGB team for their support throughout this project and sharing their website code for the construction of TGB website.

Software License

The code from this repo is licensed under the MIT License (see LICENSE)

Citation

If code or data from this repo is useful for your project, please consider citing our TGB and TGB 2.0 paper:

@article{huang2023temporal,
  title={Temporal graph benchmark for machine learning on temporal graphs},
  author={Huang, Shenyang and Poursafaei, Farimah and Danovitch, Jacob and Fey, Matthias and Hu, Weihua and Rossi, Emanuele and Leskovec, Jure and Bronstein, Michael and Rabusseau, Guillaume and Rabbany, Reihaneh},
  journal={Advances in Neural Information Processing Systems},
  year={2023}
}

@article{huang2024tgb2,
  title={TGB 2.0: A Benchmark for Learning on Temporal Knowledge Graphs and Heterogeneous Graphs},
  author={Gastinger, Julia and Huang, Shenyang and Galkin, Mikhail and Loghmani, Erfan and Parviz, Ali and Poursafaei, Farimah and Danovitch, Jacob and Rossi, Emanuele and Koutis, Ioannis and Stuckenschmidt, Heiner and      Rabbany, Reihaneh and Rabusseau, Guillaume},
  journal={Advances in Neural Information Processing Systems},
  year={2024}
}