xgdl 0.0.4

Explainability Library with Geometric Deep Learning for Scientific Tasks

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 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 manually and place raw/processed file under ./data/${DATASET_NAME}/raw or ./data/${DATASET_NAME}/processed.

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

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

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

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)

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, which should take approximately 5 minutes to install using pip on a recommended computer.

Bio
joblib
numpy
pandas
Pint
PyYAML
rdkit
rdkit_pypi
scikit_learn
scipy
tqdm
tensorboard
jupyter
pgmpy
torchmetrics

Installation

xgdl depends on the torch, make sure you have torch in your python environment and continue. If not, we suggest follow official instructions to install a suitable version.

For example,

conda install pytorch==2.3.0 cpuonly -c pytorch

This may take 3-5 minutes.

Another dependency torch_geometric need to be manually installed from outer resources. We suggest follow official instructions (Optional dependencies torch_scatter and torch_sparse for torch_geometric are required)

pip install torch_geometric
pip install torch-scatter torch-sparse torch-cluster -f https://data.pyg.org/whl/torch-${TORCH_VERSION}+${CUDA}.html

where ${TORCH_VERSION} should be replaced by your torch version and ${CUDA} should be replaced by either cpu, cu118, or cu121 depending on your PyTorch installation. For example,

pip install torch_geometric
pip install torch-scatter torch-sparse torch-cluster torch-geometric -f https://data.pyg.org/whl/torch-2.3.0+cpu.html

This may take 1-3 minutes.

Then install xgdl from pypi

pip install xgdl

or build from source

git clone https://github.com/Graph-COM/xgdl.git
cd xgdl
python install ./

This may take 4-6 minutes.

Citations

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}
}