Merge pull request #43 from monarch-initiative/develop

newer version 1.1.0
bug pointed by Peter not replicated yet. try to fix later.

.gitignore

@@ -28,7 +28,8 @@ loinc2hpo-core/src/main/resources/data_UNC_annotated.csv
 loinc2hpo-core/src/main/resources/loinc_most_frequent.csv
 loinc2hpo-core/src/resource/
 
-
+docs/build/*
+docs/source/images/figures.pptx
 # Maven
 target/
 

CHANGELOG.md

@@ -49,7 +49,33 @@ Multiple features are added. This will be the baseline for future tracking.
 * Refactor pom files. 
 
 * Refactor gitignore file. 
+
+## v1.0.4
+
+* Allow adding multiple labels to Github issues
+
+* Disable the function to clear annotation fields during manual query
+
+* Loinc entries change color if they have been annotated
+
+* Add tooltips to HPO listview and treeview
+
+* Allow user to switch to previously selected Loinc list
+
+* Allow user to categorize Loinc entries
+
+## v1.1.0 
+
+* New develop version
+
+Additional changes for this version
+
+* Change menu `Edit` to `Configuration`
+- [ ] update tutorial
+
+* Create new features that allow user to manipulate a session
 
+* Automatically retrieve information from auto-saved data for last session
 
 
 

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = loinc2hpo
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,36 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+set SPHINXPROJ=loinc2hpo
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:end
+popd

docs/source/Annotation logic.rst

@@ -0,0 +1,39 @@
+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``.
+
+
+``Qn``
+------
+
+``Qn`` or "quantitative" is the largest category of all LOINC codes, accounting for >80% in real world applications. Observations of this type have a numeric value as its outcome, such as the number of blood cells or the concentration of a substance. Annotating ``Qn`` is relatively straightforward: pick three HPO terms corresponding to the outcome of the observation when the measured value is low, intermediate or high. Here is an example for LOINC ``2823-3`` ("Potassium in Serum or Plasma"):
+
+    .. image:: images/annotation_example1.png
+
+``Ord``
+-------
+
+``Ord`` or "ordinal" is the second largest category of LOINC codes, accounting for ~14%. Ordinal type of observation has a ordered set of values as its outcome. For example, "Presence, Absence", "1, 2, 3", but the values have no linear relationship to one another. Since ordinal results are comparable to each other, many observations also use the an interpretation code to indicate whether the result is too low, normal or too high. "Presence" or "positive" can be considered as a value that is "too high", while "absence" or "negative" usually indicates that the measured value is not "too high". Therefore, one simple way to annotate this type is to pick two HPO terms, one for "too high" and the other for "intermediate":
+
+    .. image:: images/annotation_example2.png
+
+In some occasions it might become necessary to annotate each value of the outcome. The procedure becomes very similar to how we annotate nominal type LOINC (see below).
+
+``Nom``
+-------
+``Nom`` or "nominal" accounts for a small percentage of LOINC codes used in real world (~5%). Nominal observations also have a set of values as its outcomes but those values do not have an order. Therefore, one has to annotate each possible value for nominal observations (and some ordinal observations). We use LOINC ``600-7`` "Bacteria identified in Blood by Culture" as an example. The outcome could be any kind of bacteria that can infect the blood. As an example, we annotate the following finding of *Staphylococcus aureus* in blood to HP: 0002726 "Recurrent Staphylococcus aureus infections", the best available HP term currently.::
+
+  "coding":[
+  {
+    "system": "http://snomed.info/sct",
+    "code": "3092008",
+    "display": "Staphylococcus aureus"
+  }
+  ]
+
+However, it is probably not realistic to annotate every possible bacteria to an HPO term. For one thing, it is a huge task; for the other thing, it requires a term exists in HPO that matches the bacteria, which is not the case. We can summarize our finding by saying that the identification of any bacteria in the blood indicates bacteremia. Therefore, we convert the problem of mapping N outcomes to mapping 2 outcomes ("presence" or "absence" of bacteria in blood). Physicians indeed interpretate ``600-7`` observations in this manner. Even if such observations do not have such interpretations, we can always create one automatically.
+
+``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.

docs/source/Configuration.rst

@@ -0,0 +1,31 @@
+Configuration
+=============
+
+The app requires the following configurations the first time you run it.
+
+Mandatory Settings
+------------------
+
+* Download the Loinc Core Table from `loinc.org <https://loinc.org/downloads/loinc/>`_. Follow instructions from the loinc.org website. You need to register before you can download the document. The current version is *Loinc Version 2.63* (2017/12/15 release).
+
+* Configure the path to the Loinc core table. From the menu bar, click **"Edit"** - **"Set path to Loinc Core Table file"** and point to the Loinc Core Table file downloaded from last step.
+
+* Download HPO file. From the menu bar, click **"Edit"** - **"Download HPO file"**. The files (HPO in .obo and .owl formats) will be automatically downloaded.
+
+
+Optional Settings
+-----------------
+The following setting are 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.  
+
+* Set biocurator ID. From the menu bar, click **"Edit"** - **"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.
+
+* Once you are done, click **"Edit"** - **"Show settings"** to view all your settings. The first two settings should **NOT** be null in order for the app to work correctly.
+
+
+Change Settings
+---------------
+The settings will be saved to a local file so that you do not need to repeat the above steps every time you run the app. Should you want to change the settings, follow the above steps accordingly to overwrite the original settings.
+