文档 | 论文 [JMLR] | 教程 | 基准测试 | 示例 | Colab 演示 | Slack 社区:fire:

DIG：深入图学习 是一个用于图深度学习研究的开箱即用型库。

:fire:更新（2022年7月）：我们已基于 PyG 2.0.0 升级了 DIG 库。建议安装最新版本。

为什么选择 DIG？

与当前主流的图深度学习库，如 PyTorch Geometric (PyG) 和 Deep Graph Library (DGL) 相比，关键区别在于：虽然 PyG 和 DGL 主要支持基础的图深度学习操作，但 DIG 提供了一个统一的实验平台，专门针对更高层次、面向研究的图深度学习任务，例如图生成、自监督学习、可解释性、三维图以及图的分布外检测等。

如果你正在从事或计划从事图深度学习相关的研究，DIG 能够让你在我们扩展性强的框架内开发自己的方法，并使用通用的数据集和评估指标，轻松地与现有基线方法进行对比，而无需额外的工作量。

概述

DIG 包含多个高级任务的统一实现，涵盖 数据接口、常用算法和评估指标。我们的目标是让研究人员能够便捷地实现和评估各种算法。目前，我们重点关注以下研究方向：

• 图生成：dig.ggraph
• 图上的自监督学习：dig.sslgraph
• 图神经网络的可解释性：dig.xgraph
• 三维图上的深度学习：dig.threedgraph
• 图的分布外检测：dig.oodgraph
• 图增强：dig.auggraph
• 公平图学习：dig.fairgraph

使用方法

示例：只需几行代码即可在 QM9 数据集上运行 SphereNet，从而融入分子的三维信息。

from dig.threedgraph.dataset import QM93D
from dig.threedgraph.method import SphereNet
from dig.threedgraph.evaluation import ThreeDEvaluator
from dig.threedgraph.method import run

# 加载数据集并划分训练集、验证集和测试集
dataset = QM93D(root='dataset/')
target = 'U0'
dataset.data.y = dataset.data[target]
split_idx = dataset.get_idx_split(len(dataset.data.y), train_size=110000, valid_size=10000, seed=42)
train_dataset, valid_dataset, test_dataset = dataset[split_idx['train']], dataset[split_idx['valid']], dataset[split_idx['test']]

# 定义模型、损失函数和评估指标
model = SphereNet(energy_and_force=False, cutoff=5.0, num_layers=4,
                  hidden_channels=128, out_channels=1, int_emb_size=64,
                  basis_emb_size_dist=8, basis_emb_size_angle=8, basis_emb_size_torsion=8, out_emb_channels=256,
                  num_spherical=3, num_radial=6, envelope_exponent=5,
                  num_before_skip=1, num_after_skip=2, num_output_layers=3)                 
loss_func = torch.nn.L1Loss()
evaluation = ThreeDEvaluator()

# 训练和评估
run3d = run()
run3d.run(device, train_dataset, valid_dataset, test_dataset, model, loss_func, evaluation,
          epochs=20, batch_size=32, vt_batch_size=32, lr=0.0005, lr_decay_factor=0.5, lr_decay_step_size=15)

1. 有关所有包含 API 的详细信息，请参阅 文档。
2. 我们为每个方向提供了实践教程，帮助您快速上手 DIG：图生成、图上的自监督学习、图神经网络的可解释性、三维图上的深度学习、图OOD（GOOD）数据集。
3. 我们还提供了 示例，以展示如何使用 DIG 中提供的 API。您可以通过点击以下链接开始您感兴趣的领域。

• 图生成：JT-VAE、GraphAF、GraphDF、GraphEBM。
• 图上的自监督学习：InfoGraph、GRACE、MVGRL、GraphCL、LaGraph (v1 支持)。
• 图神经网络的可解释性：DeepLIFT、GNN-LRP、FlowX、GNNExplainer、GradCAM、PGExplainer、SubgraphX。
• 三维图上的深度学习：SchNet、DimeNet++、SphereNet。
• 图OOD（GOOD）数据集：GOODHIV、GOODPCBA、GOODZINC、GOODCMNIST、GOODMotif、GOODCora、GOODArxiv、GOODCBAS。

安装

通过 pip 安装

DIG: Dive into Graphs 的关键依赖包括 PyTorch（>=1.10.0）、PyTorch Geometric（>=2.0.0）和 RDKit。

1. 安装 PyTorch（>=1.10.0）

$ python -c "import torch; print(torch.__version__)"
>>> 1.10.0

2. 安装 PyG（>=2.0.0）

$ python -c "import torch_geometric; print(torch_geometric.__version__)"
>>> 2.0.0

3. 安装 DIG: Dive into Graphs。

pip install dive-into-graphs

安装完成后，您可以检查版本。如果没有出现错误，则表示您已成功安装 DIG: Dive into Graphs。

$ python
>>> from dig.version import __version__
>>> print(__version__)

从源代码安装

如果您想尝试尚未发布的最新功能，可以从源代码安装 DIG。

git clone https://github.com/divelab/DIG.git
cd DIG
pip install .

贡献

我们欢迎任何形式的贡献，例如报告错误或添加新功能。有关详细信息，请参阅我们的 贡献指南。

引用 DIG

如果您在工作中发现 DIG 有用，请引用我们的 论文：

@article{JMLR:v22:21-0343,
  author  = {Meng Liu and Youzhi Luo and Limei Wang and Yaochen Xie and Hao Yuan and Shurui Gui and Haiyang Yu and Zhao Xu and Jingtun Zhang and Yi Liu and Keqiang Yan and Haoran Liu and Cong Fu and Bora M Oztekin and Xuan Zhang and Shuiwang Ji},
  title   = {{DIG}: A Turnkey Library for Diving into Graph Deep Learning Research},
  journal = {Journal of Machine Learning Research},
  year    = {2021},
  volume  = {22},
  number  = {240},
  pages   = {1-9},
  url     = {http://jmlr.org/papers/v22/21-0343.html}
}

团队

DIG: Dive into Graphs 由 DIVE@TAMU 开发。贡献者包括 Meng Liu*、Youzhi Luo*、Limei Wang*、Yaochen Xie*、Hao Yuan*、Shurui Gui*、Haiyang Yu*、Zhao Xu、Jingtun Zhang、Yi Liu、Keqiang Yan、Haoran Liu、Cong Fu、Bora Oztekin、Xuan Zhang 和 Shuiwang Ji。

致谢

本研究部分得到了美国国家科学基金会资助，项目编号分别为 IIS-2006861、IIS-1955189、IIS-1908220、IIS-1908198、DBI-2028361 和 DBI-1922969。

联系方式

如果您有任何技术问题，请提交新的问题或在我们的 DIG Slack 社区:fire: 中提出。

如果您有其他问题，请联系：Meng Liu [mengliu@tamu.edu] 和 Shuiwang Ji [sji@tamu.edu]。

DIG (Dive into Graphs) 快速上手指南

DIG 是一个专为图深度学习研究设计的开箱即用库。与 PyG 和 DGL 等基础库不同，DIG 提供了更高级的研究任务统一测试平台，涵盖图生成、自监督学习、可解释性、3D 图以及分布外（OOD）图等方向。

1. 环境准备

在开始之前，请确保您的系统满足以下前置依赖要求：

• Python: 建议 Python 3.7+
• PyTorch: 版本 >= 1.10.0
• PyTorch Geometric (PyG): 版本 >= 2.0.0
• RDKit: 用于处理化学分子数据（特别是 3D 图任务）

注意：DIG 强依赖于特定版本的 PyTorch 和 PyG。请务必先根据您的 CUDA 版本安装对应的 PyTorch 和 PyG。

2. 安装步骤

第一步：安装 PyTorch

请访问 PyTorch 官网 获取适合您环境的安装命令。例如：

pip install torch>=1.10.0

安装后验证版本：

python -c "import torch; print(torch.__version__)"

第二步：安装 PyTorch Geometric (PyG)

根据官方文档安装 PyG 2.0.0 及以上版本：

pip install torch-geometric>=2.0.0

安装后验证版本：

python -c "import torch_geometric; print(torch_geometric.__version__)"

第三步：安装 DIG

通过 pip 直接安装稳定版：

pip install dive-into-graphs

或者，如果您想体验最新的未发布功能，可以从源码安装：

git clone https://github.com/divelab/DIG.git
cd DIG
pip install .

验证安装

运行以下代码，若无报错并输出版本号，则安装成功：

from dig.version import __version__
print(__version__)

3. 基本使用

以下示例演示了如何在 QM9 数据集上运行 SphereNet 模型，以利用分子的 3D 信息进行训练和评估。这是 dig.threedgraph 模块的典型用法。

import torch
from dig.threedgraph.dataset import QM93D
from dig.threedgraph.method import SphereNet
from dig.threedgraph.evaluation import ThreeDEvaluator
from dig.threedgraph.method import run

# 1. 加载数据集并划分
dataset = QM93D(root='dataset/')
target = 'U0'
dataset.data.y = dataset.data[target]
# 划分训练集、验证集和测试集
split_idx = dataset.get_idx_split(len(dataset.data.y), train_size=110000, valid_size=10000, seed=42)
train_dataset, valid_dataset, test_dataset = dataset[split_idx['train']], dataset[split_idx['valid']], dataset[split_idx['test']]

# 2. 定义模型、损失函数和评估器
model = SphereNet(energy_and_force=False, cutoff=5.0, num_layers=4,
                  hidden_channels=128, out_channels=1, int_emb_size=64,
                  basis_emb_size_dist=8, basis_emb_size_angle=8, basis_emb_size_torsion=8, out_emb_channels=256,
                  num_spherical=3, num_radial=6, envelope_exponent=5,
                  num_before_skip=1, num_after_skip=2, num_output_layers=3)                 
loss_func = torch.nn.L1Loss()
evaluation = ThreeDEvaluator()

# 3. 执行训练和评估
run3d = run()
device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')

run3d.run(device, train_dataset, valid_dataset, test_dataset, model, loss_func, evaluation,
          epochs=20, batch_size=32, vt_batch_size=32, lr=0.0005, lr_decay_factor=0.5, lr_decay_step_size=15)

更多资源

DIG 涵盖了多个研究方向，您可以参考以下模块进行探索：

• 图生成: dig.ggraph
• 图自监督学习: dig.sslgraph
• 图神经网络可解释性: dig.xgraph
• 3D 图深度学习: dig.threedgraph
• 图分布外学习 (OOD): dig.oodgraph

详细 API 文档和更多示例代码请访问 DIG 官方文档 或 GitHub Examples 目录。