xgdl is an explainability library for scientific tasks using geometric deep learning. (The interface is in a state of ongoing enhancement.)
- The implementation of 13 methods including self-interpretable (inherent) and post-hoc methods
- The evaluation pipeline for both sensitive and deicisve patterns (see our paper for more details)
- The dataloader module for scientific datasets.
All our datasets can be downloaded and processed automatically. By default, the code will ask if the raw files and/or the processed files should be downloaded. Also, you can download datasets from Zenodo manually and extract raw/processed file under the directory ./data/${DATASET_NAME}.
from xgdl import ScienceDataset
dataset = ScienceDataset.from_name('synmol')
key_subset = ScienceDataset.filter_signal_class(dataset)
sample = key_subset[0]Output: Data(x=[18, 1], y=[1, 1], pos=[18, 3], node_label=[18], mol_df_idx=[1], edge_index=[2, 90])
from xgdl import InherentModel
inherent_config = {
'method': "lri_bern",
'model': "egnn", # choose from ['egnn', 'dgcnn', 'pointtrans']
"dataset": "synmol", # choose from ['synmol', 'tau3mu', 'actstrack', 'plbind']
"hyperparameter":
{
'pred_loss_coef': 0.1,
'info_loss_coef': 0.05,
'temperature': 1.0,
'final_r': 0.9,
'decay_interval': 10,
'decay_r': 0.01,
'init_r': 0.5,
'attn_constraint': True
},
"training":
{
'clf_lr': 1.0e-3,
'clf_wd': 1.0e-5,
'exp_lr': 1.0e-3,
'exp_wd': 1.0e-5,
'batch_size': 4,
'epoch': 1,
}
}
inherent_explainer = InherentModel(inherent_config)
# for inherent method, use train and then explain
inherent_explainer.train(dataset)
interpretation = inherent_explainer.explain(sample)from xgdl import PosthocMethod
posthoc_config = {
'method': "gradcam",
'model': "egnn", # choose from ['egnn', 'dgcnn', 'pointtrans']
"dataset": "synmol", # choose from ['synmol', 'tau3mu', 'actstrack', 'plbind']
# "train_from_scratch": True,
"hyperparameter":
{
'pred_loss_coef': 0.1,
'info_loss_coef': 0.05,
'temperature': 1.0,
'final_r': 0.9,
'decay_interval': 10,
'decay_r': 0.01,
'init_r': 0.5,
'attn_constraint': True
},
"training":
{
'clf_lr': 1.0e-3,
'clf_wd': 1.0e-5,
'exp_lr': 1.0e-3,
'exp_wd': 1.0e-5,
'batch_size': 4,
'epoch': 1,
'warmup': 1,
}
}
posthoc_explainer = PosthocMethod(posthoc_config)
# for post_hoc method of class PostAttributor, omit train and directly explain
posthoc_explainer.train(dataset)
interpretation = posthoc_explainer.explain(sample)print(interpretation)Output: Data(x=[20, 1], y=[1, 1], pos=[20, 3], node_label=[20], mol_df_idx=[1], edge_index=[2, 100], node_imp=[20])
from xgdl import x_rocauc, fidelity
fidel = fidelity(interpretation, explainer=posthoc_explainer)
auc = x_rocauc(interpretation)This package is supported for macOS and Linux. The package has been tested on the following systems:
- macOS: Sonoma (14.2.1)
- Linux: Ubuntu 20.04
xgdl mainly depends on the following packages
torch
torch_geometric
Bio
joblib
numpy
pandas
Pint
PyYAML
rdkit
rdkit_pypi
scikit_learn
scipy
tqdm
tensorboard
jupyter
pgmpy
torchmetrics
To use xgdl, ensure that torch is installed in your Python environment. If not, please follow the official instructions to install an appropriate version.
For example with conda environment,
conda install pytorch==2.3.0 cpuonly -c pytorchThis process may take 3-5 minutes.
Additionally, torch_geometric need to be manually installed from external sources. The optional dependencies torch_scatter and torch_sparse must be installed before torch_geometric. Supported torch_geometric versions are >=2.0.0,<=2.2.0.
pip install torch-scatter torch-sparse torch-cluster -f https://data.pyg.org/whl/torch-${TORCH_VERSION}+${CUDA}.html
pip install "torch_geometric>=2.0.0,<=2.2.0"where ${TORCH_VERSION} should be replaced by your torch version and ${CUDA} should be replaced by either cpu, cu118, or cu121. For example,
pip install torch-scatter torch-sparse torch-cluster -f https://data.pyg.org/whl/torch-2.3.0+cpu.html
pip install torch-geometric==2.0.4This process may take 1-3 minutes.
To install xgdl from pypi
pip install xgdl -i https://pypi.org/simpleor build from source
git clone https://github.com/Graph-COM/xgdl.git
cd xgdl
pip install ./This process may take 4-6 minutes.
If you find our paper and repo useful, please cite our relevant paper:
@misc{zhu2024understanding,
title={Towards Understanding Sensitive and Decisive Patterns in Explainable AI: A Case Study of Model Interpretation in Geometric Deep Learning},
author={Jiajun Zhu and Siqi Miao and Rex Ying and Pan Li},
year={2024},
eprint={2407.00849},
archivePrefix={arXiv},
primaryClass={cs.LG},
url={https://arxiv.org/abs/2407.00849},
}
@article{miao2023interpretable,
title = {Interpretable Geometric Deep Learning via Learnable Randomness Injection},
author = {Miao, Siqi and Luo, Yunan and Liu, Mia and Li, Pan},
journal = {International Conference on Learning Representations},
year = {2023}
}