https://github.com/graph-com/xgdl
Explainability Library with Geometric Deep Learning for Scientific Tasks
https://github.com/graph-com/xgdl
Last synced: 7 months ago
JSON representation
Explainability Library with Geometric Deep Learning for Scientific Tasks
- Host: GitHub
- URL: https://github.com/graph-com/xgdl
- Owner: Graph-COM
- License: mit
- Created: 2024-06-11T08:36:25.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2024-10-26T02:28:55.000Z (over 1 year ago)
- Last Synced: 2025-07-19T16:53:25.006Z (7 months ago)
- Language: Python
- Homepage:
- Size: 576 KB
- Stars: 7
- Watchers: 0
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
XGDL (eXplainability for Geometric Deep Learning)
``xgdl`` is an explainability library for scientific tasks using geometric deep learning. (The interface is in a state of ongoing enhancement.)
______________________________________________________________________
## Features
- 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](https://arxiv.org/abs/2407.00849) for more details)
- The dataloader module for scientific datasets.
## Demo
### Load Dataset
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](https://doi.org/10.5281/zenodo.7265547) manually and extract raw/processed file under the directory ``./data/${DATASET_NAME}``.
```python
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])
### Use Self-interpretatble Model
```python
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)
```
### Use Post-hoc Method
```python
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)
```
### Evaluate Model Interpretation
```python
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])
```python
from xgdl import x_rocauc, fidelity
fidel = fidelity(interpretation, explainer=posthoc_explainer)
auc = x_rocauc(interpretation)
```
## System Requirements
### OS Requirements
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
### Python Dependencies
``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
```
## Installation
To use ``xgdl``, ensure that ``torch`` is installed in your Python environment. If not, please follow the [official instructions](https://pytorch.org/get-started/previous-versions/) to install an appropriate version.
For example with conda environment,
```sh
conda install pytorch==2.3.0 cpuonly -c pytorch
```
This 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``.
```sh
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,
```sh
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.4
```
This process may take 1-3 minutes.
To install ``xgdl`` from pypi
```sh
pip install xgdl -i https://pypi.org/simple
```
**or** build from source
```sh
git clone https://github.com/Graph-COM/xgdl.git
cd xgdl
pip install ./
```
This process may take 4-6 minutes.
## Citations
If you find our paper and repo useful, please cite our relevant paper:
```bibtex
@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}
}
```