{"id":19674037,"url":"https://github.com/frankaging/reascan-causal","last_synced_at":"2026-06-17T10:32:08.684Z","repository":{"id":67381890,"uuid":"384221985","full_name":"frankaging/ReaSCAN-Causal","owner":"frankaging","description":"Causal Abstraction of Neural Models Trained to Solve ReaSCAN","archived":false,"fork":false,"pushed_at":"2021-12-03T03:49:11.000Z","size":52038,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-22T10:16:01.949Z","etag":null,"topics":["causal-models","causal-networks","compositional-generalization","deep-learning","reascan"],"latest_commit_sha":null,"homepage":"https://arxiv.org/abs/2112.00826","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/frankaging.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":"2021-07-08T18:57:23.000Z","updated_at":"2021-12-06T01:05:41.000Z","dependencies_parsed_at":"2023-02-20T22:00:22.838Z","dependency_job_id":null,"html_url":"https://github.com/frankaging/ReaSCAN-Causal","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/frankaging/ReaSCAN-Causal","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frankaging%2FReaSCAN-Causal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frankaging%2FReaSCAN-Causal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frankaging%2FReaSCAN-Causal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frankaging%2FReaSCAN-Causal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/frankaging","download_url":"https://codeload.github.com/frankaging/ReaSCAN-Causal/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frankaging%2FReaSCAN-Causal/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34445179,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["causal-models","causal-networks","compositional-generalization","deep-learning","reascan"],"created_at":"2024-11-11T17:17:03.005Z","updated_at":"2026-06-17T10:32:08.678Z","avatar_url":"https://github.com/frankaging.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Interchange Intervention Training (IIT) for Compositional Reasoning in Language Grounding\nTowards Solving ReaSCAN Using Counterfactually Trained Neural Models\n\n## Release Notes\n* **10/01/2021**: We are preparing to release our code.\n\n## Contents\n* [Citation](#citation)\n* [Dataset](#dataset)\n* [Models](#models)\n* [Training](#training)\n* [Other files](#other-files)\n* [License](#license)\n\n## Citation\nIf you use this repository, please cite the following two papers: [paper for interchange intervention training](https://arxiv.org/abs/2112.00826), and [paper for the ReaSCAN dataset](https://arxiv.org/abs/2109.08994).\n```stex\n  @article{geiger-etal-2021-iit,\n        title={Inducing Causal Structure for Interpretable Neural Networks}, \n        author={Geiger, Atticus and Wu, Zhengxuan and Lu, Hanson and Rozner, Josh and Kreiss, Elisa and Icard, Thomas and Goodman, Noah D. and Potts, Christopher},\n        year={2021},\n        eprint={2112.00826},\n        archivePrefix={arXiv},\n        primaryClass={cs.LG}\n  }\n\n  @article{wu-etal-2021-reascan,\n    title={Rea{SCAN}: Compositional Reasoning in Language Grounding},\n    author={Wu, Zhengxuan and Kreiss, Elisa and Ong, Desmond C. and Potts, Christopher},\n    journal={NeurIPS 2021 Datasets and Benchmarks Track},\n    url={https://openreview.net/forum?id=Rtquf4Jk0jN},\n    year={2021}}\n```\n\n## Dataset\n\n### Off-the-shelf regenerated ReaSCAN\nWe use ReaSCAN framework to generate datasets for different experiments. In addition, we also use the `novel direction` split provided by [gSCAN](https://github.com/LauraRuis/groundedSCAN). For all the datasets we use, you can download them off-the-shelves from `ReaSCAN-Causal.zip` in this main folder.\n\n### Regenerate ReaSCAN that we use\nWe also provide you the full-fledged adpated ReaSCAN framework for you to generate datasets that we use in our experiments. The scripts we use are all in the `experiments-meta.sh` script, here is one example:\n```bash\ncd codes/Reason-SCAN/code/dataset/\n\n# using ReaSCAN framework to generate datasets.\npython generate_ReaSCAN.py \\\n--mode train \\\n--n_command_struct -1 \\\n--date 2021-09-28 \\\n--grid_size 6 \\\n--n_object_max 13 \\\n--per_command_world_retry_max 500 \\\n--per_command_world_target_count 200 \\\n--output_dir ../../data-files/ReaSCAN-Causal-ICLR-Official/ \\\n--include_relation_distractor \\\n--include_attribute_distractor \\\n--include_isomorphism_distractor \\\n--include_random_distractor \\\n--full_relation_probability 1.0 \\\n--command_pattern p1 \\\n--save_interal 50 \\\n--seed 42\n# Note that our novel direction split is directly adapted from gSCAN\n# since ReaSCAN is not supporting that yet.\n# We still provide scripts to split for novel direction, but consider\n# not to use it.\n```\n\n## Models\n\n### Multimodal LSTM\n\nThis model is published with gSCAN [in this paper](https://arxiv.org/abs/2003.05161) from [this repo](https://github.com/LauraRuis/multimodal_seq2seq_gSCAN). You can refer to their repo for details about the model. Here, we already adapt interface changes that are needed to run with ReaSCAN.\n\n## Training\n\nWe provide you training scripts for different setttings, including regular training, counterfactual training and multi-task training. We also provide you in-depth evaluation scripts that you can use to evaluate your results. You can refer to our provided scripts to see how we run our experiments in `experiments-meta.sh` and `experiments.sh`\n\nRegular training,\n```bash\ncd codes/models/seq2seq/\n\n# For regular training, you can simply run our baseline trainer.\nCUDA_VISIBLE_DEVICES=0 python run_seq2seq.py \\\n--mode=train \\\n--max_decoding_steps=120 \\\n--max_testing_examples=2000 \\\n--data_directory=../../../data-files/ReaSCAN-novel-attribute/ \\\n--input_vocab_path=input_vocabulary.txt \\\n--target_vocab_path=target_vocabulary.txt \\\n--attention_type=bahdanau \\\n--no_auxiliary_task \\\n--conditional_attention \\\n--output_directory=../../../ \\\n--training_batch_size=200 \\\n--max_training_iterations=100000 \\\n--seed=88 \\\n--learning_rate 0.002 \\\n--is_wandb\n# You can the data directory for the other task.\n# --data_directory\n```\n\nCounterfactual training for POSITION variables,\n```bash\ncd codes/models/seq2seq/\n\n# Counterfactual training for novel action sequence (direction/length).\nCUDA_VISIBLE_DEVICES=0 python run_mmlstm.py \\\n--mode=train \\\n--max_decoding_steps=120 \\\n--max_testing_examples=2000 \\\n--data_directory=../../../data-files/gSCAN-novel-direction/ \\\n--input_vocab_path=input_vocabulary.txt \\\n--target_vocab_path=target_vocabulary.txt \\\n--attention_type=bahdanau \\\n--no_auxiliary_task \\\n--conditional_attention \\\n--output_directory=../../../ \\\n--training_batch_size=200 \\\n--max_training_iterations=100000 \\\n--seed=88 \\\n--learning_rate 0.002 \\\n--is_wandb \\\n--include_task_loss \\\n--include_cf_loss \\\n--include_cf_auxiliary_loss \\\n--intervene_dimension_size 50 \\\n--cf_sample_p 1.0 \\\n--cf_loss_weight 1.0 \\\n--is_wandb\n# You can remove these flags to exclude losses.\n# --include_task_loss\n# --include_cf_loss\n# --include_cf_auxiliary_loss\n# You can the data directory for the other task.\n# --data_directory\n# You may add this option for restrict sampling of counterfactual example pairs.\n# --restrict_sampling by_direction\n# --restrict_sampling by_length\n```\n\nCounterfactual training for ATTRIBUTE variables,\n```bash\ncd codes/models/seq2seq/\n\n# Counterfactual training for novel attributes.\nCUDA_VISIBLE_DEVICES=0 python run_mmlstm_encoder.py \\\n--mode=train \\\n--max_decoding_steps=120 \\\n--max_testing_examples=2000 \\\n--data_directory=../../../data-files/ReaSCAN-novel-attribute/ \\\n--input_vocab_path=input_vocabulary.txt \\\n--target_vocab_path=target_vocabulary.txt \\\n--attention_type=bahdanau \\\n--no_auxiliary_task \\\n--conditional_attention \\\n--output_directory=../../../ \\\n--training_batch_size=200 \\\n--max_training_iterations=100000 \\\n--seed=88 \\\n--learning_rate 0.002 \\\n--include_task_loss \\\n--include_cf_loss \\\n--include_cf_auxiliary_loss \\\n--intervene_dimension_size 25 \\\n--cf_sample_p 1.0 \\\n--cf_loss_weight 1.0 \\\n--intervene_position last_hidden \\\n--is_wandb\n# You can remove these flags to exclude losses.\n# --include_task_loss\n# --include_cf_loss\n# --include_cf_auxiliary_loss\n# You may add this option for restrict sampling of counterfactual example pairs.\n# --restrict_sampling by_attribute\n\n# Counterfactual training for novel length and direction.\nCUDA_VISIBLE_DEVICES=7 python run_mmlstm.py \\\n--mode=train \\\n--max_decoding_steps=120 \\\n--max_testing_examples=2000 \\\n--data_directory=../../../data-files/gSCAN-novel-direction/ \\\n--input_vocab_path=input_vocabulary.txt \\\n--target_vocab_path=target_vocabulary.txt \\\n--attention_type=bahdanau \\\n--no_auxiliary_task \\\n--conditional_attention \\\n--output_directory=../../../ \\\n--training_batch_size=200 \\\n--max_training_iterations=100000 \\\n--seed=88 \\\n--learning_rate 0.002 \\\n--is_wandb \\\n--include_task_loss \\\n--include_cf_auxiliary_loss \\\n--intervene_dimension_size 50 \\\n--cf_sample_p 1.0 \\\n--cf_loss_weight 1.0 \\\n--is_wandb\n```\n\n## Other files\nWe also provide other helper scripts help you to visualize datasets, split datasets and etc..\n* `codes/models/seq2seq/ReaSCAN_splitter.ipynb` for splitting the datasets.\n* `codes/models/seq2seq/abstraction_graphical_model_demo.ipynb` for demonstration for our abstract models.\n\n## License\n\nReaSCAN has a [Creative Commons Attribution 4.0 International License](https://creativecommons.org/licenses/by/4.0/).\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrankaging%2Freascan-causal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffrankaging%2Freascan-causal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrankaging%2Freascan-causal/lists"}