{"id":15140705,"url":"https://github.com/qkrdmsghk/goodhse","last_synced_at":"2025-10-23T17:31:39.036Z","repository":{"id":240029181,"uuid":"801473192","full_name":"qkrdmsghk/GOODHSE","owner":"qkrdmsghk","description":"[CVPR 2024] Improving out-of-distribution generalization in graphs via hierarchical semantic environments","archived":false,"fork":false,"pushed_at":"2024-07-29T05:58:38.000Z","size":935,"stargazers_count":9,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-01-30T19:47:46.463Z","etag":null,"topics":["graph","molecule","ood-generalization"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/qkrdmsghk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2024-05-16T09:48:48.000Z","updated_at":"2024-12-24T05:42:53.000Z","dependencies_parsed_at":"2024-05-16T10:52:33.933Z","dependency_job_id":"409f7238-1b2b-47c3-bdd9-5592290e20ec","html_url":"https://github.com/qkrdmsghk/GOODHSE","commit_stats":null,"previous_names":["qkrdmsghk/goodhse"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qkrdmsghk%2FGOODHSE","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qkrdmsghk%2FGOODHSE/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qkrdmsghk%2FGOODHSE/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qkrdmsghk%2FGOODHSE/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qkrdmsghk","download_url":"https://codeload.github.com/qkrdmsghk/GOODHSE/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237869027,"owners_count":19379248,"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":["graph","molecule","ood-generalization"],"created_at":"2024-09-26T08:40:22.057Z","updated_at":"2025-10-23T17:31:39.029Z","avatar_url":"https://github.com/qkrdmsghk.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\u003ch1 align=\"center\"\u003eImproving out-of-distribution generalization in graphs via hierarchical semantic environments\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://openaccess.thecvf.com/content/CVPR2024/papers/Piao_Improving_Out-of-Distribution_Generalization_in_Graphs_via_Hierarchical_Semantic_Environments_CVPR_2024_paper.pdf\"\u003e \u003cimg alt=\"License\" src=\"https://img.shields.io/static/v1?label=Pub\u0026message=CVPR%2724\u0026color=blue\"\u003e \u003c/a\u003e\n    \u003ca href=\"https://github.com/qkrdmsghk/GOODHSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/-Github-grey?logo=github\" alt=\"Github\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://arxiv.org/abs/2403.01773\"\u003e\u003cimg src=\"https://img.shields.io/badge/arXiv-2403.01773-b31b1b.svg\" alt=\"Paper\"\u003e\u003c/a\u003e\n    \u003c!-- \u003ca href=\"https://colab.research.google.com/drive/1t0_4BxEJ0XncyYvn_VyEQhxwNMvtSUNx?usp=sharing\"\u003e\u003cimg src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Colab\"\u003e\u003c/a\u003e --\u003e\n    \u003c!-- \u003ca href=\"https://github.com/LFhase/CIGA/blob/main/LICENSE\"\u003e \u003cimg alt=\"License\" src=\"https://img.shields.io/github/license/LFhase/CIGA?color=blue\"\u003e \u003c/a\u003e --\u003e\n    \u003ca href=\"https://cvpr.thecvf.com/media/PosterPDFs/CVPR%202024/30950.png?t=1717149681.4445298\"\u003e \u003cimg src=\"https://img.shields.io/badge/Poster-grey?logo=airplayvideo\u0026logoColor=white\" alt=\"Poster\"\u003e\u003c/a\u003e\n    \u003ca href=\"./250107_GoodHSE_YinhuaPiao.pdf\"\u003e \u003cimg src=\"https://img.shields.io/badge/Slides-grey?\u0026logo=MicrosoftPowerPoint\u0026logoColor=white\" alt=\"Slides\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\n\n## Motivation\nThe complex nature of molecule graphs poses unique challenges to out-of-distribution (OOD) generalization, differentiating them from images and general graphs:\n\n1. Molecules with Similar Structures Can Have Different Functions:\n- Functional Group: Acts as a causal subgraph.\n- Scaffold: Serves as an environmental (noise) subgraph.\n\n2. Semantic Environments in OOD:\n- Environments are related.\n- Environments are hierarchical.\n\u003cp align=\"center\"\u003e\u003cimg src=\"./motivation.png\" width=80% height=100%\u003e\u003c/p\u003e\n\u003cp align=\"center\"\u003e\u003cem\u003eFigure 1.\u003c/em\u003e Challenges on molecule graphs in out-of-distribution setting.\u003c/p\u003e\n\n## Challenges\nExisting methods use flat enviornments to conduct the graph invariant learning.\nThere are two limitations in flat environment infernece:\n1. Provided (Real): neglect local similarity among the numerous environments.\n2. Inference (Infer #2): Inferring from a small number of environments may fail to capture global similarity and interrelationships among the environments. \n\u003cp align=\"center\"\u003e\u003cimg src=\"./challenge.png\" width=80% height=100%\u003e\u003c/p\u003e\n\u003cp align=\"center\"\u003e\u003cem\u003eFigure 2.\u003c/em\u003e (a) Results on IC50-SCA dataset from DrugOOD. (b) Flat environments from existing approaches. (c) Hierarchical environments from our methods. For visualization, we set #real environments as 10.\u003c/p\u003e\n\n## Compare with existing models\n\u003cp align=\"center\"\u003e\u003cimg src=\"./TLDR.png\" width=100% height=100%\u003e\u003c/p\u003e\n\n\n## Instructions\n\u003cp align=\"center\"\u003e\u003cimg src=\"./model.png\" width=80% height=100%\u003e\u003c/p\u003e\n\u003cp align=\"center\"\u003e\u003cem\u003eFigure 3.\u003c/em\u003eOur Framework consists of (a) Hierarchical Stochastic Subgraph Generation, (b) Hierarchical Semantic Environments, (c) Robust GIL with Hierarchical Semantic Environments.\u003c/p\u003e\n\n### Installation and data preparation\nOur code is based on the following libraries:\n\n```\ntorch==1.9.0+cu111\ntorch-geometric==2.0.2\n```\n\nplus the [DrugOOD](https://github.com/tencent-ailab/DrugOOD) benchmark repo.\n\nThe data used in the paper can be obtained following these [instructions](./dataset_gen/README.md).\n\n### Reproduce results\nWe provide the hyperparamter tuning and evaluation details in the paper and appendix.\nIn the below we give a brief introduction of the commands and their usage in our code. \nWe provide the corresponding running scripts in the [script](./scripts/) folder.\n\nSimply run \n```\nbash run.sh 0 icassay\n```\nwith corresponding datasets and model specifications.\n\n\n\u003c!-- Runing with CIGA:\n- `--ginv_opt` specifies the interpretable GNN architectures, which can be `asap` or `gib` to test with ASAP or GIB respectively.\n- `--r` is also needed for interpretable GNN architectures that specify the interpretable ratio, i.e., the size of $G_c$.\n- `--c_rep` controls the inputs of the contrastive learning, e.g., the graph representations from the featurizer or from the classifier\n- `--c_in` controls the inputs to the classifier, e.g., the original graph features or the features from the featurizer\n- To test with CIGAv1, simply specify `--ginv_opt` as default, and `--contrast` a value larger than `0`.\n- While for CIGAv2, additionally specify `--spu_coe` to include the other objective.\n- `--s_rep` controls the inputs for maximizing $I(\\hat{G_s};Y)$, e.g., the graph representation of $\\hat{G_s}$ from the classifier or the featurizer. --\u003e\n\n\u003c!-- Running with the baselines:\n- To test with DIR, simply specify `--ginv_opt` as default and `--dir` a value larger than `0`.\n- To test with invariant learning baselines, specify `--num_envs=2` and\nuse `--irm_opt` to be `irm`, `vrex`, `eiil` or `ib-irm` to specify the methods,\nand `--irm_p` to specify the penalty weights. --\u003e\n\n\u003c!-- Due to the additional dependence of an ERM reference model in CNC, we need to train an ERM model and save it first,\nand then load the model to generate ERM predictions for positive/negative pairs sampling in CNC. \nHere is a simplistic example: --\u003e\n\u003c!-- ```\npython main.py --erm --contrast 0 --save_model\npython main.py --erm --contrast 1  -c_sam 'cnc'\n``` --\u003e\n\n\u003c!-- ## Misc\nAs discussed in the paper that the current code is merely a prototypical implementation based on an interpretable GNN architecture, i.e., [GAE](https://arxiv.org/abs/1611.07308), in fact there could be more implementation choices:\n- For the architectures: CIGA can also be implemented via [GIB](https://github.com/Samyu0304/Improving-Subgraph-Recognition-with-Variation-Graph-Information-Bottleneck-VGIB-) and [GSAT](https://github.com/Graph-COM/GSAT). \n- For the hyperparameter tunning: You may find plentiful literature from [multi-task learning](https://github.com/median-research-group/LibMTL), or try out [PAIR](https://arxiv.org/abs/2206.07766).\n- Besides, CIGA is also compatible with state-of-the-art contrastive augmentations for graph learning, which you may find useful information from [PyGCL](https://github.com/PyGCL/PyGCL).\n\nYou can also find more discussions on the limitations and future works in Appendix B of our paper.\n\nThat being said, CIGA is definitely not the ultimate solution and it intrinsically has many limitations. \nNevertheless, we hope the causal analysis and the inspired solution in CIGA could serve as an initial step towards more reliable graph learning algorithms that are able to generalize various OOD graphs from the real world. --\u003e\n\n\nIf you find our paper and repo useful, please cite our paper: --\u003e\n\n```bibtex --\u003e\n@inproceedings{piao2024improving,\n  title={Improving out-of-distribution generalization in graphs via hierarchical semantic environments},\n  author={Piao, Yinhua and Lee, Sangseon and Lu, Yijingxiu and Kim, Sun},\n  booktitle={Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition},\n  pages={27631--27640},\n  year={2024}\n}\n```\n\nAck: The readme is inspired by [CIGA](https://github.com/LFhase/CIGA). 😄\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqkrdmsghk%2Fgoodhse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqkrdmsghk%2Fgoodhse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqkrdmsghk%2Fgoodhse/lists"}