Text Reading: Extraction Framework

Extract events from text

Overview

We extract entities and events from free text using the rule-based event extraction framework Odin (for details, see the associated github Wiki and the user manual. Extracted events are represented as Mentions objects that contain all the essential information about the event, including the text of the mention, the trigger⁺ (if present), the arguments, and more. The number of arguments in each mention depends on the type of event extracted. The explanations on the entities and events currently extracted can be found on this page.

We apply this extraction framework to reading the text of scientific publications, source comments, and model documents (i.e., READMEs). Event extraction includes applying Odin grammar rules to free text and refining the produced Mentions using a set of heuristics (e.g., expanding variable descriptions to complete phrases and filtering out apparent false positives). This document text reading produces two types of alignment elements: text_var, which is the variable argument of extracted Definition mentions (e.g., LAI, Tmax) and text_span, which is the definition argument of extracted Definition mentions (e.g., leaf area index, maximum temperature). In the future, we will expand the inventory of text-based link elements to include parameter settings (or constraints) and units, both of which we extract, but are not currently aligning.

Applying the event extraction framework to source comments, we extract comment definition mentions with two arguments: variable and definition, with the latter used as the comment_span element in the alignment pipeline. Source comments that we handle follow a standard pattern of <variable name> <variable definition> (<optional unit>), so simple rules with basic heuristics (e.g., a variable cannot be a number) are currently sufficient; additionally, if source code variables are available in the input to the alignment pipeline, we only keep comment definitions whose variables overlap with the source code variables.

Extracting mentions from scientific publications is a relatively time-consuming step (#todo: time estimate), so it is done offline. Source comments tend to be sparse enough to allow for quick processing, which means that unlike text mentions, mentions from source comments can be extracted as part of running the full pipeline (see the code here).

⁺ A trigger is a word or a phrase that is used in a rule-based system to signal the presence of an event of interest.

Usage:

Mention Extraction:

To extract mentions from the json files we produced during Step 1, use the /jsonDoc_to_mentions endpoint. The endpoint takes as input a json object with the following structure:

• 'json' : <path to the json file produced by Science Parse>.

To send requests via the endpoint, you need to have the webapp running (see more here). You can extract mentions by using CURL:

> curl \
  --header "Content-type: application/json" \
  --request POST \
  --data '<input JSON object>' \
  http://localhost:9000/jsonDoc_to_mentions

Example of the data argument: --data '{"json": "userDir/petpno_Penman.json"}'

NOTE: Steps 1 and 2 can be done jointly by using the pdf_to_mentions endpoint, which requires that Science Parse is running and takes as input a JSON with the following parameter:

• pdf: the path to the PDF file to process

> curl \
  --header "Content-type: application/json" \
  --request POST \
  --data '<input JSON file>' \
  http://localhost:9000/pdf_to_mentions

Note: an alternative way to extract mentions from PDFs is described here.

Rule Writing:

The rule-writing framework is flexible. It allows the user to extract events with multiple arguments, use dependency graphs or surface patterns, add constrains to extractions using regular expressions, incorporate previously extracted events, and more. As a gentle introduction, here we provide two examples of the rules we use in our reading system (see all the rules here).

An example of a dependency-based rule:

  - name: var_cop_definition                        #has to be unique
    label: Definition                               #the event label
    priority: Int                                   #shows the order in which rules (or rule batches) are going to be applied 
    type: dependency                                 #rule based on a dependency graph
    example: "LAI is the actual leaf area index"
    action: ${action}                                #an action (or a heuristic) to apply after the event is extracted with a rule to filter out undesired output 
    pattern: |
      trigger = [lemma="be"]                         #a word/lemma/pos-tag that is indicative of the event 
      variable:Concept = (<cop /${agents}/ | <cop <dep appos ) [!entity = /NUMBER|B-unit/ & !word = "=" & !word = ","] #<argument 1>:<the type of entity the argument can be>; the argument can be reached through the dependency relation paths 
      definition: Concept = <cop (?! case) nmod_for? compound? [!entity = /NUMBER|B-unit/] #argument 2

The rule extracts a Definition event with two arguments: variable (here LAI) and definition (here leaf area index).

An example of a token-based rule:

  - name: var_definition
    label: Definition
    priority: Int
    type: token
    example: "EEQ Equilibrium evaporation (mm/d)"
    pattern: |
       @variable:Variable (?<definition> [word = /.*/ & !tag="-LRB-"]+) 

This rules is used to extract events from source code comments. Here, we extract a definition event that includes two arguments: a previously extracted ¹ Variable (here EEQ), which will be the variable argument, and a previously unseen ² definition (here Equilibrium evaporation).

¹ following the pattern: @<arg_name>:<Label_of_previously_found_Mention>

² the syntax to assign a label to a pattern: (?<label> pattern)