Package: qanom
QANom - Annotating Nominal Predicates with QA-SRLQANom is a research project aiming for a natural representation of nominalization's predicate-argument relations.
It extends the Question Answer driven Semantic Role Labeling (QASRL) framework (seewebsite), which tackled verbal predicates,
to the more challenging space of deverbal nominalizations.This repository is the reference point for the data and software described in the paperQANom: Question-Answer driven SRL for Nominalizations(COLING 2020).
To find information for replicating the work described by the QANom paper (crowdsourcing a QANom dataset, identifying nominalization candidates, training and evaluating the baseline models), please refer to thepaper_reference_readme.md.The repo also consists software for using QANom downstream.
This mainly includes pipelines for easy usage of thenominalization detection modeland of theQANom parsers.
This README will guide you through using this software.Pre-requisitePython 3.7InstallationFrom pypi:pip install qanomIf you want to install from source, clone this repository and then install requirements:gitclonehttps://github.com/kleinay/QANom.gitcdQANom
pipinstallrequirements.txtEnd-to-End PipelineIf you wish to parse sentences with QANom, the best place to start is theQANomEndToEndPipelineclass from theqanom.qanom_end_to_end_pipelinemodule.This pipeline is first running theNominalization Detectorfor identifying the nominal predicates in the sentence (seedemo).
Then, it sends each nominal predicate to theQAnom-Seq2Seq model(seedemo) to parse them with Question-Answer driven Semantic Role Labeling (QASRL).Usage Examplefromqanom.qanom_end_to_end_pipelineimportQANomEndToEndPipelinepipe=QANomEndToEndPipeline(detection_threshold=0.75)sentence="The construction of the officer 's building finished right after the beginning of the destruction of the previous construction ."print(pipe([sentence]))Output:[[{'QAs':[{'question':'what was constructed ?','answers':["the officer 's"]}],'predicate_idx':1,'predicate':'construction','predicate_detector_probability':0.7623529434204102,'verb_form':'construct'},{'QAs':[{'question':'what began ?','answers':['the destruction of the']}],'predicate_idx':11,'predicate':'beginning','predicate_detector_probability':0.8923847675323486,'verb_form':'begin'},{'QAs':[{'question':'what was destructed ?','answers':['the previous']}],'predicate_idx':14,'predicate':'destruction','predicate_detector_probability':0.849774956703186,'verb_form':'destruct'}]]Nominalization Detection ModelThis model identifies "predicative nominalizations", that is, nominalizations that carry an eventive (or "verbal") meaning in context. It is abert-base-casedpretrained model, fine-tuned for token classification on top of the "nominalization detection" task as defined and annotated by the QANom project.The model is trained as a binary classifier, classifying candidate nominalizations.
The candidates are extracted using a POS tagger (filtering common nouns) and additionally lexical resources (e.g. WordNet and CatVar), filtering nouns that have (at least one) derivationally-related verb. In the QANom annotation project, these candidates are given to annotators to decide whether they carry a "verbal" meaning in the context of the sentence. The current model reproduces this binary classification.Under the hood, theNominalizationDetectorclass encapsulates the full nominalization detection pipeline (i.e. candidate extraction + predicate classification).
It leverages theqanom.candidate_extraction.candidate_extraction.pymodule, and additionally downloads and wraps thenominalization-candidate-classifiermodel, hosted at Huggingface model hub.Usage Examplefromqanom.nominalization_detectorimportNominalizationDetectordetector=NominalizationDetector()raw_sentences=["The construction of the officer 's building finished right after the beginning of the destruction of the previous construction ."]print(detector(raw_sentences,return_all_candidates=True))print(detector(raw_sentences,threshold=0.75,return_probability=False))Outputs:[[{'predicate_idx':1,'predicate':'construction','predicate_detector_prediction':True,'predicate_detector_probability':0.7626778483390808,'verb_form':'construct'},{'predicate_idx':4,'predicate':'officer','predicate_detector_prediction':False,'predicate_detector_probability':0.19832570850849152,'verb_form':'officer'},{'predicate_idx':6,'predicate':'building','predicate_detector_prediction':True,'predicate_detector_probability':0.5794129371643066,'verb_form':'build'},{'predicate_idx':11,'predicate':'beginning','predicate_detector_prediction':True,'predicate_detector_probability':0.8937646150588989,'verb_form':'begin'},{'predicate_idx':14,'predicate':'destruction','predicate_detector_prediction':True,'predicate_detector_probability':0.8501205444335938,'verb_form':'destruct'},{'predicate_idx':18,'predicate':'construction','predicate_detector_prediction':True,'predicate_detector_probability':0.7022264003753662,'verb_form':'construct'}]][[{'predicate_idx':1,'predicate':'construction','verb_form':'construct'},{'predicate_idx':11,'predicate':'beginning','verb_form':'begin'},{'predicate_idx':14,'predicate':'destruction','verb_form':'destruct'}]]SpaCy Custom Component 'nominalization_detector'If you are using SpaCy, you can easily plug-in our nominalization detection algorithm as a custom component into theSpaCy pipeline. Load theqanom.spacy_component_nominalization_detectormodule to have our "nominalization_detector" component registered by spacy.For example:fromqanom.spacy_component_nominalization_detectorimport*nlp=spacy.load("en_core_web_sm")nlp.add_pipe("nominalization_detector",after="tagger",config={"threshold":0.7,"device":-1})# you may specify config settings or stay with these defaults# Now you `nlp` pipeline also identifies verbal nominalizations:doc=nlp("The medical student asked about the progress in Luke's treatment.")print(doc._.nominalizations)# a Doc extension attribute with the list of tokens identified as verbal nominalizationsprint([(nn.text,nn._.verb_form,nn._.is_nominalization_confidence)fornnindoc._.nominalizations])# Token extension attributes[progress, treatment]
[('progress', 'progress', 0.8063599467277527),
 ('treatment', 'treat', 0.8211929798126221)]QANom Sequence-to-Sequence ModelsWe have finetuned T5, a pretrained Seq-to-Seq language model, on the task of parsing QANom QAs.
Given a sentence and a highlighted nominal predicate, the models produce an output sequence consisting of the QANom-formatted question-answer pairs for this predicate.We currently have two models:qanom-seq2seq-model-baseline(HF repo) - trained only on the QANom dataset. Performance: 57.6 Unlabled Arg F1, 34.9 Labeled Arg F1.qanom-seq2seq-model-joint(HF repo) - trained jointly on the QANom and verbal QASRL. Performance: 60.1 Unlabled Arg F1, 40.6 Labeled Arg F1.We provide theQASRL_Pipelineclass (at `qanom.qasrl_seq2seq_pipeline) which is a Huggingface Pipeline for applying the models out-of-the-box on new texts:frompipelineimportQASRL_Pipelinepipe=QASRL_Pipeline("kleinay/qanom-seq2seq-model-baseline")pipe("The student was interested in Luke 's <predicate> research about see animals .",verb_form="research",predicate_type="nominal")Which will output:[{'generated_text':'who _ _ researched something _ _ ?<extra_id_7> Luke','QAs':[{'question':'who researched something ?','answers':['Luke']}]}]You can learn more about usingtransformers.pipelinesin theofficial docs.Notice that you need to specify which word in the sentence is the predicate, about which the question will interrogate. By default, you should precede the predicate with the<predicate>symbol, but you can also specify your own predicate marker:pipe("The student was interested in Luke 's <PRED> research about see animals .",verb_form="research",predicate_type="nominal",predicate_marker="<PRED>")In addition, you can specify additional kwargs for controling the model's decoding algorithm:pipe("The student was interested in Luke 's <predicate> research about see animals .",verb_form="research",predicate_type="nominal",num_beams=3)Cite@inproceedings{klein2020qanom,
 title={QANom: Question-Answer driven SRL for Nominalizations},
 author={Klein, Ayal and Mamou, Jonathan and Pyatkin, Valentina and Stepanov, Daniela and He, Hangfeng and Roth, Dan and Zettlemoyer, Luke and Dagan, Ido},
 booktitle={Proceedings of the 28th International Conference on Computational Linguistics},
 pages={3069--3083},
 year={2020}}