{"id":19603889,"url":"https://github.com/divelab/leci","last_synced_at":"2025-04-27T19:32:27.271Z","repository":{"id":181254809,"uuid":"664094382","full_name":"divelab/LECI","owner":"divelab","description":"The implementation of \"Joint Learning of Label and Environment Causal Independence for Graph Out-of-Distribution Generalization\" (NeurIPS 2023)","archived":false,"fork":false,"pushed_at":"2024-11-04T17:00:06.000Z","size":170,"stargazers_count":19,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"LECI-1.0.0","last_synced_at":"2025-04-22T14:56:26.088Z","etag":null,"topics":["deep-learning","graph-neural-networks","graph-out-of-distriubion","out-of-distribution-generalization","pytorch","pytorch-geometric"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/divelab.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}},"created_at":"2023-07-08T22:36:13.000Z","updated_at":"2025-02-25T03:26:43.000Z","dependencies_parsed_at":"2024-11-04T18:17:47.152Z","dependency_job_id":null,"html_url":"https://github.com/divelab/LECI","commit_stats":null,"previous_names":["divelab/leci"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/divelab%2FLECI","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/divelab%2FLECI/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/divelab%2FLECI/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/divelab%2FLECI/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/divelab","download_url":"https://codeload.github.com/divelab/LECI/tar.gz/refs/heads/LECI-1.0.0","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251195909,"owners_count":21550866,"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":["deep-learning","graph-neural-networks","graph-out-of-distriubion","out-of-distribution-generalization","pytorch","pytorch-geometric"],"created_at":"2024-11-11T09:33:26.525Z","updated_at":"2025-04-27T19:32:26.566Z","avatar_url":"https://github.com/divelab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Joint Learning of Label and Environment Causal Independence for Graph Out-of-Distribution Generalization\n\n[![arXiv](https://img.shields.io/badge/arXiv-2306.01103-b31b1b.svg)](https://arxiv.org/abs/2306.01103)\n\u003ca href=\"https://openreview.net/forum?id=z3HACY5CMa\"\u003e \u003cimg alt=\"License\" src=\"https://img.shields.io/static/v1?label=Pub\u0026message=NeurIPS%2723\u0026color=blue\"\u003e \u003c/a\u003e\n[![License][license-image]][license-url]\n\nThis is the official code for the implementation of \"Joint Learning of Label and Environment Causal Independence for Graph Out-of-Distribution Generalization\"\nwhich is accepted by NeurIPS 2023. :smile:\n\n[license-url]: https://github.com/divelab/LECI/blob/main/LICENSE\n[license-image]:https://img.shields.io/badge/license-GPL3.0-green.svg\n\n\n## Table of contents\n\n* [Overview](#overview)\n* [Installation](#installation)\n* [Run LECI](#run-leci)\n* [Citing LECI](#citing-leci)\n* [License](#license)\n* [Contact](#contact)\n\n## Overview\n\nIn this work, we propose to simultaneously incorporate label and environment causal independence (LECI) to \nrelease the potential of pre-collected environment information in graph tasks, thereby addressing the challenges faced by prior methods on identifying \ncausal/invariant subgraphs. We further develop an adversarial training strategy to jointly optimize these two properties for \ncausal subgraph discovery with theoretical guarantees.\n\n\n## Installation \n\n### Conda dependencies\n\nLECI depends on [PyTorch (\u003e=1.6.0)](https://pytorch.org/get-started/previous-versions/), [PyG (\u003e=2.0)](https://pytorch-geometric.readthedocs.io/en/latest/notes/installation.html), and\n[RDKit (\u003e=2020.09.5)](https://www.rdkit.org/docs/Install.html). For more details: [conda environment](/../../blob/main/environment.yml)\n\n\u003e Note that we currently test on PyTorch (==1.10.1), PyG (==2.0.3), RDKit (==2020.09.5); thus we strongly encourage to install these versions.\n\n### Project installation\n\n```shell\ngit clone https://github.com/divelab/LECI.git \u0026\u0026 cd LECI\npip install -e .\n```\n\n## Run LECI\n\n```shell\ngoodtg --config_path final_configs/GOODHIV/scaffold/covaraite/LECI.yaml --exp_round [1/2/3/4/5/6/7/8/9/10] --gpu_idx [0..9]\ngoodtg --config_path final_configs/GOODHIV/size/covaraite/LECI.yaml --exp_round [1/2/3/4/5/6/7/8/9/10] --gpu_idx [0..9]\ngoodtg --config_path final_configs/LBAPcore/assay/covaraite/LECI.yaml --exp_round [1/2/3/4/5/6/7/8/9/10] --gpu_idx [0..9]\ngoodtg --config_path final_configs/GOODMotif/basis/covaraite/LECI.yaml --exp_round [1/2/3/4/5/6/7/8/9/10] --gpu_idx [0..9]\ngoodtg --config_path final_configs/GOODMotif/size/covaraite/LECI.yaml --exp_round [1/2/3/4/5/6/7/8/9/10] --gpu_idx [0..9]\ngoodtg --config_path final_configs/GOODCMNIST/color/covaraite/LECI.yaml --exp_round [1/2/3/4/5/6/7/8/9/10] --gpu_idx [0..9]\ngoodtg --config_path final_configs/GOODSST2/length/covaraite/LECI.yaml --exp_round [1/2/3/4/5/6/7/8/9/10] --gpu_idx [0..9]\ngoodtg --config_path final_configs/GOODTwitter/length/covaraite/LECI.yaml --exp_round [1/2/3/4/5/6/7/8/9/10] --gpu_idx [0..9]\n```\n\nTo run the code without installing the project, please replace `goodtg` with `python -m GOOD.kernel.main`.\n\nExplanations of the arguments can be found in this [file](/../../blob/LECI-1.0.0/configs/GOOD_configs/GOODMotif/basis/covariate/LECI.yaml).\n\n### How to train LECI?\n\n**Valid LECI:** The training of LECI is valid only when the optimal discriminator [Proposition 3.2](https://arxiv.org/pdf/2306.01103.pdf) is approximately learned, *e.g.*, \nthe environment branch loss at least should not indicate a random prediction when the adversarial training is not applied (or is weak). Note that the adversarial intensity\nincreases from 0 to $\\lambda_{EA}$ as the training proceeds, which is controlled by `self.config.train.alpha` in the code. \n\n\n**How to select the right learning rate?** Since the environment labels $E$ are noisier than normal classification labels, LECI starts with lower learning rates than general GNNs.\n\n**How to select the valid hyperparameters?** If the EA/LA loss never decreases (invalid LECI), please try decreasing $\\lambda_{EA}$ and $\\lambda_{LA}$.\n\nFor more details, please refer to the appendix of [our paper](https://openreview.net/pdf?id=z3HACY5CMa).\n\n## Citing LECI\nIf you find this repository helpful, please cite our [paper](https://openreview.net/forum?id=z3HACY5CMa)/[preprint](https://arxiv.org/abs/2306.01103).\n```\n@inproceedings{gui2023joint,\n  title={Joint Learning of Label and Environment Causal Independence for Graph Out-of-Distribution Generalization},\n  author={Gui, Shurui and Liu, Meng and Li, Xiner and Luo, Youzhi and Ji, Shuiwang},\n  booktitle={Thirty-seventh Conference on Neural Information Processing Systems},\n  year={2023},\n  url={https://openreview.net/forum?id=z3HACY5CMa}\n}\n```\n\n## License\n\n- The GOOD datasets are under [MIT license](https://drive.google.com/file/d/1xA-5q3YHXLGLz7xV2tT69a9dcVmiJmiV/view?usp=sharing).\n- The DrugOOD dataset is under [GPLv3](https://github.com/tencent-ailab/DrugOOD/blob/main/LICENSE)\n- The LECI code are under [GPLv3 license](/../../blob/main/LICENSE), since the code architecture is based on [GOOD](https://github.com/divelab/GOOD.git).\n\n## Discussion\n\nPlease submit [new issues](/../../issues/new) or start [a new discussion](/../../discussions/new) for any technical or other questions.\n\n## Contact\n\nPlease feel free to contact [Shurui Gui](mailto:shurui.gui@tamu.edu) or [Shuiwang Ji](mailto:sji@tamu.edu)!\n\n## Acknowledgements\n\nThis work was supported in part by National Science Foundation grants IIS-2006861 and IIS-1908220.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdivelab%2Fleci","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdivelab%2Fleci","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdivelab%2Fleci/lists"}