Merge pull request #52 from monarch-initiative/develop

Develop

docs/source/Annotation logic.rst

@@ -1,7 +1,7 @@
 Annotation Logic
 ================
 
-The key to successful annotation is to anticipate what kind of outcome is for a LOINC code. Since the outcome is strongly associated with the ``Scale`` parameter of LOINC, we will describe three main types separately. For more detailed description of LOINC, refer to ``Intro to LOINC``.
+The key to successful annotation is to anticipate what kinds of outcome are for a LOINC code. Since the outcome is strongly associated with the ``Scale`` parameter of LOINC, we will describe three main types separately. For more detailed description of LOINC, refer to ``Intro to LOINC``.
 
 
 ``Qn``
@@ -11,6 +11,9 @@ The key to successful annotation is to anticipate what kind of outcome is for a
 
     .. image:: images/annotation_example1.png
 
+**Term Negation**
+As you can see from the above example, we assigned the negated form of "HP:0011015 Abnormality of blood glucose concentration" to the intermediate value. Intermediate value usually means "normal", e.g. in this case, so by default the term that you choose for intermediate value is always negated. However, there are cases when this is not true, e.g. LOINC 9269-2 Glasgow coma score total, where the intermediate value is not interpreted as "no coma" but instead "mild coma". So you will need to uncheck the "negate" checkbox in this case.
+
 ``Ord``
 -------
 
@@ -36,4 +39,4 @@ However, it is probably not realistic to annotate every possible bacteria to an
 
 ``Nar`` and other types
 -----------------------
-Other types of LOINC codes are much more heterogeneous, making their interpretation much more challenging. Since they only account for 1% of real world applications, we will not consider those LOINC codes for now. But in future, we may attempt to use those those resources with natural language processing, image analysis etc.
+Other types of LOINC codes are much more heterogeneous, making their interpretation much more challenging. Since they only account for 1% of real world applications, we will not consider those LOINC codes for now. But in future, we may attempt to use those those resources with natural language processing, image analysis etc.

docs/source/Configuration.rst

@@ -17,12 +17,12 @@ Mandatory Settings
 
 Optional Settings
 -----------------
-The following setting are recommended. Not specifying them will not
+The following setting are strongly recommended. Not specifying them will not
 affect the operation of the app. 
 
-* Change the directory for auto-saved data. The default directory for auto-saved data is located at ~/.loinc2hpo/Data. If you want to change this setting,  from the menu bar, click **Configuration** - **Set path to Autosaved Data** to change the directory for autosaved data.
+* Change the directory for auto-saved data. The default directory for auto-saved data is located at ~/.loinc2hpo/Data. If you want to change this setting, click **Configuration** - **Set path to Autosaved Data** to select your desired directory.
 
-  note: this step is mandatory if you want to use and push your annotation to `loinc2hpoAnnotation <https://github.com/TheJacksonLaboratory/loinc2hpoAnnotation>`_. Follow instructions there to set up the path properly.
+  **Note:** this step is mandatory if you want to use and push your annotations to `loinc2hpoAnnotation <https://github.com/TheJacksonLaboratory/loinc2hpoAnnotation>`_. Follow instructions there to set up the path properly.
 
 * Set biocurator ID. From the menu bar, click **"Configuration"** - **"Set biocurator ID"**, specify your biocurator ID. If you are not assigned one, create one for yourself with the following format: organization name first, then `:`, then your name/id.
 

docs/source/Tutorial.rst

@@ -3,8 +3,8 @@ Tutorial
 
 This tutorial is for loinc2hpo V1.1.0.
 
-Tabs
-----
+Overview
+--------
 The app has three tabs.
 
 ``Annotate``: contains functions for annotating LOINC codes (mapping LOINC codes to HPO terms);
@@ -26,7 +26,7 @@ Follow the steps to start the curation process.
 
 - Import LOINC codes. If you have configured the app properly, you should be able to see there are contents in the LOINC table. You can always click **"Initialize Loinc Table"** on the left upper corner to import Loinc codes from the Loinc Core Table file. Try using the "Search" function to select some Loinc codes, e.g. try searching for "10449-7" and then "glucose" (You will get one result for "10449-7" and many results for "glucose").
 
-- Import HPO. Click "Initialize HPO model" on the left upper corner to import all HPO terms to the app.
+- Import HPO. Click "Initialize HPO model" on the left upper corner to import all HPO terms to the app. If you configured the app properly, this will automatically run when you start the app.
 
 - After completing the above steps, you should be able to start annotating LOINC codes!
   - Go to the Loinc Table in the bottom half of the tab, and choose the LOINC code that you want to annotate. When you click the **"Auto Query"** button or double click on the LOINC code, the app will automatically find candidate HPO terms for you, listed from the most likely term to the least likely.
@@ -59,6 +59,8 @@ Follow the steps to start the curation process.
 
 - Manually search for candidate HPO terms. If `Auto Query` does not give you the HPO terms that you need, try using the `Manual Query` button with comma-separated keys. Tip: *try synonyms*; words without comma will be taken as one key and the app will try to find a exact match to it.
 
+- Group LOINC. Sometimes you may not be able to annotate a LOINC code because you are waiting for new HPO terms (see below: ``Suggest new HPO terms``) or you simply do not know how to annotate it. You can group LOINC into a list so that your collaborators can help. Right click on the LOINC code, choose `Group/ungroup` and select a list. By default there will be two groups, "require_new_HPO_terms" and "unable_to_annotate". You can create more groups but the app does not display their colors very well yet (working on it!).
+
 
 **Review/Edit your annotations**
 
@@ -109,9 +111,9 @@ In the Basic Mode, the **"negate"** button only controls the term in the center
 Suggest new HPO terms
 ~~~~~~~~~~~~~~~~~~~~~
 
-Sometimes you may not be able to find an appropriate HPO term for a LOINC code. You can send a request for new terms to the authors of HPO directly from the app.
+Sometimes you may not be able to find an appropriate HPO term for a LOINC code. You can send a request to the authors of HPO directly from the app to ask for new terms.
 
-- Create a new term for a Loinc code. Select a Loinc code and then click **"Suggest New HPO term"**. Provide the proposed term and your comment, type in your GitHub username and GitHub password, choose a label that best describes your request, e.g. `new term request`, and click **"Create GitHub issue"**.
+- Create a new term for a Loinc code. Select a Loinc code and then click **"Suggest New HPO term"**. Provide the proposed term and your comment, type in your GitHub username and GitHub password, choose a label that best describes your request, e.g. `LOINC`, and click **"Create GitHub issue"**.
 
 - Create a new child term for a Loinc code. If a current HPO term is close to what you need but you need a new child beneath it, you can select both the Loinc code and the candidate HPO term, right-click, select **"Suggest child term"**, fill in relevant information and submit.
 

loinc2hpogui/src/main/resources/fxml/annotateTab.fxml

@@ -176,6 +176,9 @@
                           </items>
                         </ContextMenu>
                      </contextMenu>
+                     <VBox.margin>
+                        <Insets bottom="20.0" left="10.0" right="10.0" />
+                     </VBox.margin>
                   </ListView>
                   <HBox prefHeight="0.0" prefWidth="737.0">
                      <children>