{"id":32639554,"url":"https://github.com/cogcomp/jointconstrainedlearning","last_synced_at":"2025-10-31T02:13:15.817Z","repository":{"id":45729191,"uuid":"332775794","full_name":"CogComp/JointConstrainedLearning","owner":"CogComp","description":"Joint Constrained Learning for Event-Event Relation Extraction","archived":false,"fork":false,"pushed_at":"2021-07-01T11:32:13.000Z","size":1767,"stargazers_count":25,"open_issues_count":0,"forks_count":4,"subscribers_count":6,"default_branch":"main","last_synced_at":"2024-04-28T05:11:54.590Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Jupyter Notebook","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/CogComp.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}},"created_at":"2021-01-25T14:35:16.000Z","updated_at":"2023-11-24T07:38:10.000Z","dependencies_parsed_at":"2022-09-15T01:53:19.285Z","dependency_job_id":null,"html_url":"https://github.com/CogComp/JointConstrainedLearning","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/CogComp/JointConstrainedLearning","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CogComp%2FJointConstrainedLearning","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CogComp%2FJointConstrainedLearning/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CogComp%2FJointConstrainedLearning/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CogComp%2FJointConstrainedLearning/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CogComp","download_url":"https://codeload.github.com/CogComp/JointConstrainedLearning/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CogComp%2FJointConstrainedLearning/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281914584,"owners_count":26583088,"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","status":"online","status_checked_at":"2025-10-31T02:00:07.401Z","response_time":57,"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":[],"created_at":"2025-10-31T02:13:13.410Z","updated_at":"2025-10-31T02:13:15.811Z","avatar_url":"https://github.com/CogComp.png","language":"Jupyter Notebook","readme":"# Joint Constrained Learning for Event-Event Relation Extraction\n\nThis is the repository for the resources in EMNLP 2020 Paper [\"Joint Constrained Learning for Event-Event Relation Extraction\"](https://www.aclweb.org/anthology/2020.emnlp-main.51/). This repository contains the source code and datasets used in our paper.\n\n## Abstract\n\nUnderstanding natural language involves recognizing how multiple event mentions structurally and temporally interact with each other. In this process, one can induce event complexes that organize multi-granular events with temporal order and membership relations interweaving among them. Due to the lack of jointly labeled data for these relational phenomena and the restriction on the structures they articulate, we propose a joint constrained learning framework for modeling event-event relations. Specifically, the framework enforces logical constraints within and across multiple temporal and subevent relations by converting these constraints into differentiable learning objectives. We show that our joint constrained learning approach effectively compensates for the lack of jointly labeled data, and outperforms SOTA methods on benchmarks for both temporal relation extraction and event hierarchy construction, replacing a commonly used but more expensive global inference process. We also present a promising case study showing the effectiveness of our approach in inducing event complexes on an external corpus.\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://github.com/why2011btv/JointConstrainedLearning/blob/master/example/Example.jpg?raw=true\" alt=\"drawing\" width=\"500\"/\u003e\n\u003c/p\u003e\n\n## Dataset\n\nTwo datasets ([MATRES](https://github.com/why2011btv/JointConstrainedLearning/tree/master/MATRES) and [HiEve](https://github.com/why2011btv/JointConstrainedLearning/tree/master/hievents_v2)) are used for training in the paper. \n\n## How to train\n### Environment Setup et al.\n```\ngit clone https://github.com/why2011btv/JointConstrainedLearning.git\nconda env create -n conda-env -f env/environment.yml\npip install -r env/requirements.txt\npython spacy -m en-core-web-sm\n\nmkdir rst_file\nmkdir model_params\ncd model_params\nmkdir HiEve_best\nmkdir MATRES_best\ncd ..\n```\n### Running experiments in the paper\n`python3 main.py \u003cDEVICE_ID\u003e \u003cBATCH_SIZE\u003e \u003cRESULT_FILE\u003e \u003cEPOCH\u003e \u003cSETTING\u003e \u003cLOSS\u003e \u003cFINETUNE\u003e \u003cMAX_EVALS\u003e \u003cDEBUGGING\u003e`\n\n`\u003cDEVICE_ID\u003e`: choose from \"gpu_0\", \"gpu_1\", \"gpu_5,6,7\", etc.\n\n`\u003cBATCH_SIZE\u003e`: choose from \"batch_16\" (with finetuning), \"batch_500\" (w/o finetuning)\n\n`\u003cRESULT_FILE\u003e`: for example, \"0920_0.rst\"\n\n`\u003cEPOCH\u003e`: choose from \"epoch_40\", \"epoch_80\", etc.\n\n`\u003cSETTING\u003e`: choose from \"MATRES\", \"HiEve\", \"Joint\"\n\n`\u003cLOSS\u003e`: choose from \"add_loss_0\" (w/o constraints), \"add_loss_1\" (within-task constraints), \"add_loss_2\" (within \u0026 cross task constraints)\n\n`\u003cFINETUNE\u003e`: choose from \"finetune_0\" (roberta-base emb w/o finetuning + BiLSTM), \"finetune_1\" (roberta-base emb with finetuning, no BiLSTM)\n\n`\u003cMAX_EVALS\u003e`: number of times for hyperopt to run experiments for finding best hyperparameters, choose from \"MAX_EVALS_50\", etc.\n\n`\u003cDEBUGGING\u003e`: whether to debug, choose from \"debugging_0\", \"debugging_1\"\n\n### Example commands \n#### Command for \"Joint Constrained Learning\" with all constraints and RoBERTa finetuning, using hyperopt for finding best hyperparameters\n`nohup python3 main.py gpu_0 batch_16 0118_0.rst epoch_40 Joint add_loss_2 finetune_1 MAX_EVALS_50 debugging_0 \u003e output_redirect/0118_0.out 2\u003e\u00261 \u0026`\n\nTo look at the standard output: `cat output_redirect/0118_0.out`\n\n#### Command for training using a specific set of hyperparameters\n`nohup python3 main.py gpu_0 batch_16 0118_1.rst epoch_40 Joint add_loss_2 finetune_1 MAX_EVALS_1 debugging_1 \u003e output_redirect/0118_1.out 2\u003e\u00261 \u0026`\n\nYou need to specify the hyperparameters in [main.py](https://github.com/why2011btv/JointConstrainedLearning/blob/56818c48e50af01a6b2f85252a91cf9e2c20fbf7/main.py#L51). You can find the hyperparameter settings under [config](https://github.com/why2011btv/JointConstrainedLearning/tree/master/config) folder.\n\n## How to predict\n\n### Input \u0026 Output\n\nInput should be a json file that contains a list of dictionaries. Each dictionary contains four key-value pairs, i.e., two sentences and two char id's denoting the start position of events. Two examples can be found under [example](https://github.com/why2011btv/JointConstrainedLearning/tree/master/example) folder, you can also find more details on generating input json file in [example/example_input_for_predict.ipynb](https://github.com/why2011btv/JointConstrainedLearning/blob/master/example/example_input_for_predict.ipynb).\n\nOutput will also be a json file under [output](https://github.com/why2011btv/JointConstrainedLearning/tree/master/output) folder. The output contains a dictionary with two key-value pairs; one is labels, the other is predicted probabilities.\n\n### How to run \n`python3 predict.py \u003cINPUT_FILE\u003e \u003cTASK\u003e \u003cMODEL\u003e \u003cOUTPUT_FILE\u003e`\n\n`\u003cINPUT_FILE\u003e`: a json file\n\n`\u003cTASK\u003e`: choose from \"subevent\" and \"temporal\"\n\n`\u003cMODEL\u003e`: choose from \"MATRES\", \"HiEve\", \"Joint\" (i.e., dataset on which the model was trained)\n\n`\u003cOUTPUT_FILE\u003e`: name for a json file\n\n### Example commands\n#### Command for predicting temporal relations\n`python predict.py example/temporal_example_input.json temporal MATRES predict_temporal.json`\n#### Command for predicting subevent relations\n`python predict.py example/subevent_example_input.json subevent Joint predict_subevent.json`\n\n#### [Link to pre-trained model](https://drive.google.com/drive/folders/1PyNAlNHY144pGsko9iYxwYlqf4ud0Lq1?usp=sharing)\n\n\n## Reference\nBibtex:\n```\n@inproceedings{WCZR20,\n    author = {Haoyu Wang and Muhao Chen and Hongming Zhang and Dan Roth},\n    title = {{Joint Constrained Learning for Event-Event Relation Extraction}},\n    booktitle = {Proc. of the Conference on Empirical Methods in Natural Language Processing (EMNLP)},\n    year = {2020},\n    url = \"https://cogcomp.seas.upenn.edu/papers/WCZR20.pdf\",\n    funding = {KAIROS},\n}\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcogcomp%2Fjointconstrainedlearning","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcogcomp%2Fjointconstrainedlearning","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcogcomp%2Fjointconstrainedlearning/lists"}