README.md (10741B)
1 # Text2Event 2 3 - An implementation for [``Text2Event: Controllable Sequence-to-Structure Generation for End-to-end Event Extraction``](https://aclanthology.org/2021.acl-long.217) 4 - Please contact [Yaojie Lu](http://luyaojie.github.io) ([@luyaojie](mailto:yaojie2017@iscas.ac.cn)) for questions and suggestions. 5 6 ## Update 7 - [2021-08-03] Update pre-trained models 8 9 ## Quick links 10 * [Requirements](#Requirements) 11 * [Quick Start](#Quick-start) 12 * [Data Format](#Data-Format) 13 * [Model Training](#Model-Training) 14 * [Model Evaluation](#Model-Evaluation) 15 * [How to expand to other tasks](#How-to-expand-to-other-tasks) 16 * [Pre-trained Model](#Pre-trained-Model) 17 * [Event Datasets Preprocessing](#Event-Datasets-Preprocessing) 18 * [Citation](#Citation) 19 20 ## Requirements 21 22 General 23 24 - Python (verified on 3.8) 25 - CUDA (verified on 11.1) 26 27 Python Packages 28 29 - see requirements.txt 30 31 ```bash 32 conda create -n text2event python=3.8 33 conda activate text2event 34 pip install -r requirements.txt 35 ``` 36 37 ## Quick Start 38 39 ### Data Format 40 41 Data folder contains four files (The detailed preprocessing steps refer to `Event Datasets Preprocessing`): 42 43 ```text 44 data/text2tree/one_ie_ace2005_subtype 45 ├── event.schema 46 ├── test.json 47 ├── train.json 48 └── val.json 49 ``` 50 51 train/val/test.json are data files, and each line is a JSON instance. 52 Each JSON instance contains `text` and `event` fields, in which `text` is plain text, and `event` is event linearized form. 53 If you want to use other key names, it is easy to change the input format in `run_seq2seq.py`. 54 55 ```text 56 {"text": "He also owns a television and a radio station and a newspaper .", "event": "<extra_id_0> <extra_id_1>"} 57 {"text": "' ' For us the United Natgions is the key authority '' in resolving the Iraq crisis , Fischer told reporters opn arrival at the EU meeting .", "event": "<extra_id_0> <extra_id_0> Meet meeting <extra_id_0> Entity EU <extra_id_1> <extra_id_1> <extra_id_1>"} 58 ``` 59 60 Note: 61 - Use the extra character of T5 as the structure indicators, such as `<extra_id_0>`, `<extra_id_1>`, etc. 62 - `event.schema` is the event schema file for building the trie of constrained decoding. 63 It contains three lines: the first line is event type name list, the second line is event role name list, the third line is type-to-role dictionary. 64 65 ```text 66 ["Declare-Bankruptcy", "Convict", ...] 67 ["Plaintiff", "Target", ...] 68 {"End-Position": ["Place", "Person", "Entity"], ...} 69 ``` 70 71 ### Model Training 72 73 Training scripts as follows: 74 75 - `run_seq2seq.py`: Python code entry, modified from the transformers/examples/seq2seq/run_seq2seq.py 76 - `run_seq2seq.bash`: Model training script logging to the log file. 77 - `run_seq2seq_verbose.bash`: Same model training script as `run_seq2seq.bash` but output to the screen directly. 78 - `run_seq2seq_with_pretrain.bash`: Model training script for curriculum learning, which contains substructure learning and full structure learning. 79 80 The command for the training is as follows (see bash scripts and Python files for the corresponding command-line 81 arguments): 82 83 ```bash 84 bash run_seq2seq_verbose.bash -d 0 -f tree -m t5-base --label_smoothing 0 -l 1e-4 --lr_scheduler linear --warmup_steps 2000 -b 16 85 ``` 86 87 - `-d` refers to the GPU device id. 88 - `-m t5-base` refers to using T5-base. 89 - Currently, constrained decoding algorithms do not support `use_fast_tokenizer=True` and beam search yet. 90 91 Trained models are saved in the `models/` folder. 92 93 ### Model Evaluation 94 95 Offset-level Evaluation 96 97 ```bash 98 python evaluation.py -g <data-folder-path> -r <offset-folder-path> -p <model-folder-path> -f <data-format> 99 ``` 100 - This evaluation script converts the `eval_preds_seq2seq.txt` and `test_preds_seq2seq.txt` in the model folder `<model-folder-path>` into the corresponding offset prediction results for model evaluation. 101 - ``-f <data-format>`` refers to `dyiepp` or `oneie` 102 103 Record-level Evaluation (approximate, used in training) 104 105 ```bash 106 bash run_eval.bash -d 0 -m <model-folder-path> -i <data-folder-path> -c -b 8 107 ``` 108 109 - `-d` refers to the GPU device id. 110 - `-c` represents the use of constrained decoding, otherwise not apply 111 - `-b 8` represents `batch_size=8` 112 113 ### How to expand to other tasks 114 115 1. prepare the corresponding data format 116 2. Writ the code for reading corresponding data format: `elif data_args.task.startswith("event")` in `seq2seq.py` 117 3. Writ the code for evaluating the corresponding task result: `def compute_metrics(eval_preds)` in `seq2seq.py` 118 119 Completing the above process can finish the simple Seq2Seq training and inference process. 120 121 If you need to use constrained decoding, you need to write the corresponding decoding mode (decoding_format), refer to `extraction.extract_constraint.get_constraint_decoder` 122 123 ## Pre-trained Model 124 125 You can find the pre-trained models as following google drive links or download models using command `gdown` (`pip install gdown`). 126 127 [dyiepp_ace2005_en_t5_base.zip](https://drive.google.com/file/d/1_fOmnSatNfceL9DZPxpof5AT9Oo7vTrC/view?usp=sharing) 128 ```bash 129 gdown --id 1_fOmnSatNfceL9DZPxpof5AT9Oo7vTrC && unzip dyiepp_ace2005_en_t5_base.zip 130 ``` 131 132 [dyiepp_ace2005_en_t5_large.zip](https://drive.google.com/file/d/10iY1obkbgJtTKwfoOFevqL5AwG-hLvhU/view?usp=sharing) 133 ```bash 134 gdown --id 10iY1obkbgJtTKwfoOFevqL5AwG-hLvhU && unzip dyiepp_ace2005_en_t5_large.zip 135 ``` 136 137 [oneie_ace2005_en_t5_large.zip](https://drive.google.com/file/d/1zwnptRbdZntPT4ucqSANeaJ3vvwKliUe/view?usp=sharing) 138 ```bash 139 gdown --id 1zwnptRbdZntPT4ucqSANeaJ3vvwKliUe && unzip oneie_ace2005_en_t5_large.zip 140 ``` 141 142 [oneie_ere_en_t5_large.zip](https://drive.google.com/file/d/1WG7-pTZ3K49VMbQIONaDq_0pUXAcoXrZ/view?usp=sharing) 143 ```bash 144 gdown --id 1WG7-pTZ3K49VMbQIONaDq_0pUXAcoXrZ && unzip oneie_ere_en_t5_large.zip 145 ``` 146 147 ## Event Datasets Preprocessing 148 149 We first refer to the following code and environments [[dygiepp](https://github.com/dwadden/dygiepp)] and [[oneie v0.4.7](http://blender.cs.illinois.edu/software/oneie/)] for data preprocessing. 150 Thanks to them！ 151 152 ### DYGIEPP ACE05 153 Generated Path: `dygiepp/data/ace-event/processed-data/default-settings/json/` 154 155 Preprocessing Script: 156 ``` bash 157 python ./scripts/data/ace-event/parse_ace_event.py default-settings 158 ``` 159 160 The version of spacy is `2.0.18`, it may affect results of sentence splitting. And the version of dygiepp I used as follows 161 ``` 162 commit edec203b73d32824f14e03b5510e020130b69a7f (HEAD -> master) 163 Author: dwadden <dwadden@cs.washington.edu> 164 Date: Sun Oct 11 15:02:33 2020 -0700 165 166 Add `dataset` argument when creating new doc-key. 167 ``` 168 169 ### OneIE ACE05+ 170 ``` bash 171 ACE_DATA_FOLDER=<ACE_PATH> 172 mkdir -p data/ace05-EN 173 python preprocessing/process_ace.py -i ${ACE_DATA_FOLDER}/data -o data/ace05-EN -s resource/splits/ACE05-E -b bert-large-cased -l english 174 wc -l data/ace05-EN/* 175 ``` 176 177 - `nltk==3.5` is used in our experiments, we found `nltk==3.6+` may leads different sentence numbers. 178 179 180 After data preprocessing and we get the following data files: 181 182 ```text 183 $ tree data/raw_data/ 184 data/raw_data/ 185 ├── ace05-EN 186 │ ├── dev.oneie.json 187 │ ├── test.oneie.json 188 │ └── train.oneie.json 189 ├── dyiepp_ace2005 190 │ ├── dev.json 191 │ ├── test.json 192 │ └── train.json 193 └── ERE-EN 194 ├── dev.oneie.json 195 ├── test.oneie.json 196 └── train.oneie.json 197 ``` 198 199 We then convert the above data files to tree format. 200 The following scripts generate the corresponding data folder in `data/text2tree`. 201 The conversion will automatically generate `train/dev/test` JSON files and `event.schema` file. 202 203 ```bash 204 bash scripts/processing_data.bash 205 ``` 206 207 ```text 208 data/text2tree 209 ├── dyiepp_ace2005_subtype 210 │ ├── event.schema 211 │ ├── test.json 212 │ ├── train.json 213 │ └── val.json 214 ├── dyiepp_ace2005_subtype_span 215 │ ├── event.schema 216 │ ├── test.json 217 │ ├── train.json 218 │ └── val.json 219 ├── one_ie_ace2005_subtype 220 │ ├── event.schema 221 │ ├── test.json 222 │ ├── train.json 223 │ └── val.json 224 ├── one_ie_ace2005_subtype_span 225 │ ├── event.schema 226 │ ├── test.json 227 │ ├── train.json 228 │ └── val.json 229 ├── one_ie_ere_en_subtype 230 │ ├── event.schema 231 │ ├── test.json 232 │ ├── train.json 233 │ └── val.json 234 └── one_ie_ere_en_subtype_span 235 ├── event.schema 236 ├── test.json 237 ├── train.json 238 └── val.json 239 ``` 240 241 - `dyiepp_ace2005_subtype` for Full Structure Learning and `dyiepp_ace2005_subtype_span` for Substructure Learning. 242 243 ## Citation 244 245 If this repository helps you, please cite this paper: 246 247 Yaojie Lu, Hongyu Lin, Jin Xu, Xianpei Han, Jialong Tang, Annan Li, Le Sun, Meng Liao, Shaoyi Chen. Text2Event: Controllable Sequence-to-Structure Generation for End-to-end Event Extraction. The Joint Conference of the 59th Annual Meeting of the Association for Computational Linguistics and the 11th International Joint Conference on Natural Language Processing (ACL-IJCNLP 2021). 248 249 ``` 250 @inproceedings{lu-etal-2021-text2event, 251 title = "{T}ext2{E}vent: Controllable Sequence-to-Structure Generation for End-to-end Event Extraction", 252 author = "Lu, Yaojie and 253 Lin, Hongyu and 254 Xu, Jin and 255 Han, Xianpei and 256 Tang, Jialong and 257 Li, Annan and 258 Sun, Le and 259 Liao, Meng and 260 Chen, Shaoyi", 261 booktitle = "Proceedings of the 59th Annual Meeting of the Association for Computational Linguistics and the 11th International Joint Conference on Natural Language Processing (Volume 1: Long Papers)", 262 month = aug, 263 year = "2021", 264 address = "Online", 265 publisher = "Association for Computational Linguistics", 266 url = "https://aclanthology.org/2021.acl-long.217", 267 pages = "2795--2806", 268 abstract = "Event extraction is challenging due to the complex structure of event records and the semantic gap between text and event. Traditional methods usually extract event records by decomposing the complex structure prediction task into multiple subtasks. In this paper, we propose Text2Event, a sequence-to-structure generation paradigm that can directly extract events from the text in an end-to-end manner. Specifically, we design a sequence-to-structure network for unified event extraction, a constrained decoding algorithm for event knowledge injection during inference, and a curriculum learning algorithm for efficient model learning. Experimental results show that, by uniformly modeling all tasks in a single model and universally predicting different labels, our method can achieve competitive performance using only record-level annotations in both supervised learning and transfer learning settings.", 269 } 270 ```