create a reaction/fact

tm_curation/curate_from_tm.md

@@ -5,10 +5,24 @@ This excercise will cover:
 - building a simple fact using selected entries
 - building an advanced fact
 
+## Read first: vocabulary and data model
+
+BioKC relies on [SBML (Systems Biology Markup Language)](https://sbml.org) as its underlying data model and follows [annotation qualifiers](http://mbine.org/standards/qualifiers) for its annotations. This influences the vocabulary of BioKC.  
+
+Important vocabulary disambiguations:
+- **compartment** a physical or conceptual location of elements of interactions
+- **species** are elements of interactions; in SBML every species has an assigned  compartment
+- **reactions** describe interactions between interacting elements: **reactants** and **products**
+- **modifiers** are elements of a reaction (interaction) with a specific role; in SBML  a reaction can have an element that modifies them.
+
+In SBML, a reaction (interaction) must have at least one reactant (input) and at least one product (output).
+
+In SBML, a reaction can have multiple reactants, products and modifiers. Reaction type is the same for reactants and products. Each modifier can have a different role (type of modifying relationship).
+
 ## Table of contents
 - [Literature collection](#literature-collection)
 - [Step 1: Import sentences](#step-1-import-sentences-from-the-data-set)
-- [Step 1: Curate from basket](#step-2-build-facts-from-entries-in-the-basket)
+- [Step 2: Curate from basket](#step-2-build-facts-from-entries-in-the-basket)
 
 ## Literature collection
 
@@ -38,41 +52,76 @@ The file contains a table with the following columns:
 
 ### 1.2. Import sentences from a file
     
-1.2.1 Choose the "indra_biokc.tsv" file
+1.2.1 Choose the "indra_biokc.tsv" file (1 in the figure below)
 
-1.2.2 Explore sentences from the file are imported and shown in the area below
+1.2.2 Explore sentences from the file are imported and shown in the area below (2 in the figure below)
 
 ![import](../images/1_2_import.png)
 
 ### 1.3. Filter by keywords
 	
-1.3.1 Type the keyword you want to filter entries by; this can be a publication identifier, molecule identifier or a term in the sentence.  
+1.3.1 Type the keyword you want to filter entries by; this can be a publication identifier, molecule identifier or a term in the sentence. Example: use "tnf" as a keyword (1 in the figure below). 
 Important to note:
 - text based searches are less precise ("tnf" query will have more results than "P01375")
 - multiple keywords can be combined wtih space as a separator (e.g. "TNF IKK") 
 
-1.3.2 Notice that the number of results is dynamically reduced
+1.3.2 Notice that the number of results is dynamically reduced (2 in the figure below)
 
 ![filter](../images/1_3_filter_imported_sentences.png)
 
 ### 1.4. Add entries to the "Curator's basket"
     
-1.4.1 Select entries you want to curate; metadata is fetched for publication identifiers 
+1.4.1 Select entries you want to curate; metadata is fetched for publication identifiers (1 in the figure below)
 
-1.4.2 Notice that data from selected entries is added to the "Curator's basket"
+1.4.2 Notice that data from selected entries is added to the "Curator's basket" (2 in the figure below)
 
-1.4.3 Click "Go to basket" to start curation using the selected entries
+1.4.3 Click "Go to basket" to start curation using the selected entries (3 in the figure below)
 	
 ![go to basket](../images/1_4_select_basket.png)
 
 ## Step 2: Build facts from entries in the Basket
 
+Take a look at the [vocabulary disclaimer](#read-first-vocabulary-and-data-model) to read about species (elements), compartments (location) and reactions (interactions).
+
 ### 2.1. Initial steps
 
-2.1.1 In the "Curator's basket", notice the entries selected in the previous step
+2.1.1 In the "Curator's basket", notice the entries selected in the previous step (1 in the figure below)
+
+2.1.2 Set the fact group to "Training"; this is where your facts will be saved (persisted) later (2 in the figure below)
+
+2.1.3 Set up the initial compartment for the facts, use ![menuadd](../images/0_add.png) button to add a compartment and ![menuedit](../images/0_edit.png) to edit it. In the example below, the compartment is set to "cell" with the [qualifier annotation](http://mbine.org/standards/qualifiers) set to "bqbiol:is", annotation ontology set to "Cell Ontology" and the assigned identifier to [CL:0000000 (cell)](http://purl.obolibrary.org/obo/CL_0000000) (3 in the figure below).
+
+![set up basket](../images/2_1_basket_details_inset.png)
+
+### 2.2. Add elements
+
+2.2.1 Drag and drop elements of an interaction. Example: drag "TNF" and "p65".
+
+![drag drop](../images/2_2_move.png)
+
+2.2.2 Cell type and element type need to be defined for the imported elements.  
+
+Example: 
+- use previolusly defined "cell" as the "Compartment"
+- set "Bioentity type" to "Generic protein"
+- set identifier namespace to "Uniprot Knowledgebase".  
+
+Repeat for p65 and set its name to "RELA" by modifying the field "Species Name".
+
+![tnf complete](../images/2_3_complete.png)
+
+2.2.3 With defined elements, create an interaction: use ![menuadd](../images/0_add.png) button to add a compartment and ![menuedit](../images/0_edit.png) to edit it. Complete the information to create a simple interaction representing positive influence of TNF on RELA (p65).  
+
+- use previolusly defined "cell" as the "Compartment"
+- set "Reaction type" to "Positive influence"
+- set "Reactant" to "TNF" and "Product" to "RELA".  
+
+![simple reaction](../images/2_4_reaction.png)
+
+2.2.4 With defined interaction, create a fact and annotate it with the sentence. Use ![menuadd](../images/0_add.png) button to add a fact. Then:
 
-2.1.2 Set the fact group to "Training"; this is where your facts will be saved (persisted) later
+1. Drag created reaction to the reaction area of the fact.
 
-2.1.3 Set up the initial compartment for the facts, use ![menuadd](../images/0_add.png) button to add a compartment and ![menuedit](../images/0_edit.png) to edit it. In the example below, the compartment is set to "cell" with the [qualifier annotation](http://mbine.org/standards/qualifiers) set to "bqbiol:is", annotation ontology set to "Cell Ontology" and the assigned identifier to [CL:0000000 (cell)](http://purl.obolibrary.org/obo/CL_0000000).
+2. Drag the corresponding field to the evidence area of the fact.
 
-![set up basket](../images/2_1_basket_details_inset.png)
\ No newline at end of file
+![drag fact elements](../images/2_5_fact_p1.png)