{"id":22229747,"url":"https://github.com/graph-com/xgdl","last_synced_at":"2025-07-20T06:32:17.789Z","repository":{"id":244220706,"uuid":"813516938","full_name":"Graph-COM/xgdl","owner":"Graph-COM","description":"Explainability Library with Geometric Deep Learning for Scientific Tasks","archived":false,"fork":false,"pushed_at":"2024-10-26T02:28:55.000Z","size":590,"stargazers_count":7,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-07-19T16:53:25.006Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Graph-COM.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-06-11T08:36:25.000Z","updated_at":"2025-07-11T14:08:09.000Z","dependencies_parsed_at":"2024-07-30T07:33:44.757Z","dependency_job_id":"a0d334ac-443a-434f-a3f2-50fdf7790325","html_url":"https://github.com/Graph-COM/xgdl","commit_stats":null,"previous_names":["graph-com/xgdl"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Graph-COM/xgdl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Graph-COM%2Fxgdl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Graph-COM%2Fxgdl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Graph-COM%2Fxgdl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Graph-COM%2Fxgdl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Graph-COM","download_url":"https://codeload.github.com/Graph-COM/xgdl/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Graph-COM%2Fxgdl/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266076350,"owners_count":23872741,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-03T01:12:12.361Z","updated_at":"2025-07-20T06:32:17.758Z","avatar_url":"https://github.com/Graph-COM.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eXGDL (eXplainability for Geometric Deep Learning)\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://pypi.python.org/pypi/xgdl\"\u003e\u003cimg src=\"https://badge.fury.io/py/xgdl.svg\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://arxiv.org/abs/2407.00849\"\u003e\u003cimg src=\"https://img.shields.io/badge/-arXiv-grey?logo=gitbook\u0026logoColor=white\" alt=\"Paper\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/Graph-COM/xgdl\"\u003e\u003cimg src=\"https://img.shields.io/badge/-Github-grey?logo=github\" alt=\"Github\"\u003e\u003c/a\u003e\n    \u003ca\u003e \u003cimg alt=\"License\" src=\"https://img.shields.io/badge/Under%20Review-blue\"\u003e \u003c/a\u003e\n\u003c/p\u003e\n\n``xgdl`` is an explainability library for scientific tasks using geometric deep learning. (The interface is in a state of ongoing enhancement.)\n______________________________________________________________________\n## Features\n- The implementation of 13 methods including self-interpretable (inherent) and post-hoc methods\n- The evaluation pipeline for both sensitive and deicisve patterns (see our [paper](https://arxiv.org/abs/2407.00849) for more details)\n- The dataloader module for scientific datasets.\n\n## Demo\n\n### Load Dataset\nAll 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}``.\n\n```python\nfrom xgdl import ScienceDataset    \n\ndataset = ScienceDataset.from_name('synmol')\nkey_subset = ScienceDataset.filter_signal_class(dataset)\nsample = key_subset[0]\n```\n\n\u003e Output: Data(x=[18, 1], y=[1, 1], pos=[18, 3], node_label=[18], mol_df_idx=[1], edge_index=[2, 90])\n\n### Use Self-interpretatble Model\n```python\nfrom xgdl import InherentModel\n\ninherent_config = {\n        'method': \"lri_bern\",\n        'model': \"egnn\", # choose from ['egnn', 'dgcnn', 'pointtrans']\n        \"dataset\": \"synmol\", # choose from ['synmol', 'tau3mu', 'actstrack', 'plbind']\n        \"hyperparameter\":\n            {\n            'pred_loss_coef': 0.1,\n            'info_loss_coef': 0.05,\n            'temperature': 1.0,\n            'final_r': 0.9,\n            'decay_interval': 10,\n            'decay_r': 0.01,\n            'init_r': 0.5,\n            'attn_constraint': True\n            },\n        \"training\":\n            {\n            'clf_lr': 1.0e-3,\n            'clf_wd': 1.0e-5,\n            'exp_lr': 1.0e-3,\n            'exp_wd': 1.0e-5,\n            'batch_size': 4,\n            'epoch': 1,\n            }\n        }\n\ninherent_explainer = InherentModel(inherent_config)\n\n# for inherent method, use train and then explain\ninherent_explainer.train(dataset)\ninterpretation = inherent_explainer.explain(sample)\n\n```\n### Use Post-hoc Method\n```python\nfrom xgdl import PosthocMethod\n\nposthoc_config = {\n    'method': \"gradcam\",\n    'model': \"egnn\", # choose from ['egnn', 'dgcnn', 'pointtrans']\n    \"dataset\": \"synmol\", # choose from ['synmol', 'tau3mu', 'actstrack', 'plbind']\n    # \"train_from_scratch\": True,\n    \"hyperparameter\":\n    {\n        'pred_loss_coef': 0.1,\n        'info_loss_coef': 0.05,\n        'temperature': 1.0,\n        'final_r': 0.9,\n        'decay_interval': 10,\n        'decay_r': 0.01,\n        'init_r': 0.5,\n        'attn_constraint': True\n    },\n    \"training\":\n        {\n        'clf_lr': 1.0e-3,\n        'clf_wd': 1.0e-5,\n        'exp_lr': 1.0e-3,\n        'exp_wd': 1.0e-5,\n        'batch_size': 4,\n        'epoch': 1,\n        'warmup': 1,\n        }\n}\n\nposthoc_explainer = PosthocMethod(posthoc_config)\n\n# for post_hoc method of class PostAttributor, omit train and directly explain\nposthoc_explainer.train(dataset)\ninterpretation = posthoc_explainer.explain(sample)\n```\n\n### Evaluate Model Interpretation\n\n```python\nprint(interpretation)\n```\n\u003e 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])\n\n```python\nfrom xgdl import x_rocauc, fidelity\n\nfidel = fidelity(interpretation, explainer=posthoc_explainer)\nauc = x_rocauc(interpretation)\n\n```\n\n## System Requirements\n### OS Requirements\nThis package is supported for *macOS* and *Linux*. The package has been tested on the following systems:\n+ macOS: Sonoma (14.2.1)\n+ Linux: Ubuntu 20.04\n\n### Python Dependencies\n``xgdl`` mainly depends on the following packages\n```\ntorch\ntorch_geometric\nBio\njoblib\nnumpy\npandas\nPint\nPyYAML\nrdkit\nrdkit_pypi\nscikit_learn\nscipy\ntqdm\ntensorboard\njupyter\npgmpy\ntorchmetrics\n```\n\n## Installation\nTo 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.\nFor example with conda environment,\n```sh\nconda install pytorch==2.3.0 cpuonly -c pytorch\n```\nThis process may take 3-5 minutes.\n\nAdditionally, ``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 ``\u003e=2.0.0,\u003c=2.2.0``.   \n```sh\npip install torch-scatter torch-sparse torch-cluster -f https://data.pyg.org/whl/torch-${TORCH_VERSION}+${CUDA}.html\npip install \"torch_geometric\u003e=2.0.0,\u003c=2.2.0\"\n```\nwhere ``${TORCH_VERSION}`` should be replaced by your torch version and ``${CUDA}`` should be replaced by either ``cpu``, ``cu118``, or ``cu121``. For example,\n```sh\npip install torch-scatter torch-sparse torch-cluster -f https://data.pyg.org/whl/torch-2.3.0+cpu.html\npip install torch-geometric==2.0.4\n```\nThis process may take 1-3 minutes.\n\nTo install ``xgdl`` from pypi\n\n```sh\npip install xgdl -i https://pypi.org/simple\n```\n**or** build from source\n```sh\ngit clone https://github.com/Graph-COM/xgdl.git\ncd xgdl\npip install ./\n```\nThis process may take 4-6 minutes.\n\n## Citations\n\nIf you find our paper and repo useful, please cite our relevant paper:\n```bibtex\n@misc{zhu2024understanding,\n      title={Towards Understanding Sensitive and Decisive Patterns in Explainable AI: A Case Study of Model Interpretation in Geometric Deep Learning}, \n      author={Jiajun Zhu and Siqi Miao and Rex Ying and Pan Li},\n      year={2024},\n      eprint={2407.00849},\n      archivePrefix={arXiv},\n      primaryClass={cs.LG},\n      url={https://arxiv.org/abs/2407.00849}, \n}\n\n@article{miao2023interpretable,\n  title       = {Interpretable Geometric Deep Learning via Learnable Randomness Injection},\n  author      = {Miao, Siqi and Luo, Yunan and Liu, Mia and Li, Pan},\n  journal     = {International Conference on Learning Representations},\n  year        = {2023}\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgraph-com%2Fxgdl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgraph-com%2Fxgdl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgraph-com%2Fxgdl/lists"}