Merge pull request #109 from monarch-initiative/develop

Develop
monarch-initiative · Jul 9, 2023 · d364f3c · d364f3c
2 parents 11430b4 + acc0af0
commit d364f3c
Show file tree

Hide file tree

Showing 38 changed files with 391 additions and 252 deletions.
diff --git a/.gitignore b/.gitignore
@@ -22,3 +22,7 @@ dependency-reduced-pom.xml
 hs_err_pid*
 
 src/test/resource/
+docs/build/
+docs/venv/
+pom.xml.versionsBackup
+.vscode
diff --git a/docs/img/PhenoteAnnot1.png b/docs/img/PhenoteAnnot1.png
diff --git a/docs/img/PhenoteAnnot2.png b/docs/img/PhenoteAnnot2.png
diff --git a/docs/img/PhenoteAutocomplete.png b/docs/img/PhenoteAutocomplete.png
diff --git a/docs/img/PhenoteFileMenu.png b/docs/img/PhenoteFileMenu.png
diff --git a/docs/img/PhenoteNew.png b/docs/img/PhenoteNew.png
diff --git a/docs/img/PhenoteSetup.png b/docs/img/PhenoteSetup.png
diff --git a/docs/img/PhenoteTextMining1.png b/docs/img/PhenoteTextMining1.png
diff --git a/docs/img/PhenoteTextMining2.png b/docs/img/PhenoteTextMining2.png
diff --git a/docs/img/PhenoteTextMining3.png b/docs/img/PhenoteTextMining3.png
diff --git a/docs/img/PhenoteTextMining4.png b/docs/img/PhenoteTextMining4.png
diff --git a/docs/img/PhenoteTextMining5.png b/docs/img/PhenoteTextMining5.png
diff --git a/docs/img/PhenoteTextMining6.png b/docs/img/PhenoteTextMining6.png
diff --git a/docs/img/triphalangeal-annot.png b/docs/img/triphalangeal-annot.png
diff --git a/docs/img/triphalangeal.png b/docs/img/triphalangeal.png
diff --git a/docs/index.rst b/docs/index.rst
@@ -25,8 +25,13 @@ The best place to leave feedback, ask questions, and report bugs is the `Phenote
 
     install
     tutorial_setup
+    tutorial_file
+    tutorial_create_new
+    tutorial_add_annotation
+    tutorial_text_mining
+    tutorial_sharing
     tutorial_local_hpo
-    tutorial_working
+
 
 .. toctree::
     :caption: Project Info

diff --git a/docs/install.rst b/docs/install.rst
@@ -33,7 +33,7 @@ Prerequisites
 
 For building PhenoteFX, you will need
 
-#. `Java JDK 16 or higher <http://www.oracle.com/technetwork/java/javase/downloads/index.html>`_ for compiling OntoLib,
+#. `Java JDK 17 or higher <http://www.oracle.com/technetwork/java/javase/downloads/index.html>`_ for compiling OntoLib,
 #. `Maven <http://maven.apache.org/>`_ for building PhenoteFX, and
 #. `Git <http://git-scm.com/>`_ for getting the sources.
 

diff --git a/docs/release_howto.rst b/docs/release_howto.rst
diff --git a/docs/requirements.txt b/docs/requirements.txt
diff --git a/docs/tutorial_add_annotation.rst b/docs/tutorial_add_annotation.rst
@@ -0,0 +1,90 @@
+.. _add_annot:
+
+==================
+Adding annotations
+==================
+
+The PhenoteFX app requires each annotation to have a citation from PubMed. Therefore, the first thing to do is to 
+grab the pubmed id from the article you are curating.
+
+For this example, we will use data from 
+`Klopocki E, et al. (2008_) A microduplication of the long range SHH limb regulator (ZRS) 
+is associated with triphalangeal thumb-polysyndactyly syndrome. J Med Genet. 45:370-5 <https://pubmed.ncbi.nlm.nih.gov/18178630/>`_.
+
+The corresponding ID that PhenoteFX expects is ``PMID:18178630`` (no space in between PMID: and the number, but PhenoteFX will 
+automatically remove spaces when you paste the id into the dialog).
+
+
+
+.. figure:: img/PhenotePMID.png
+    :scale: 50 %
+    :align: center
+    :alt: PhenoteFX - specifying the PubMed id 
+
+Paste the PMID into the ``source `` field, as shown above.
+
+
+Now we can add the first annotation. In this case, we will add the mode of inheritance as 
+`Autosomal dominant inheritance HP:0000006 <https://hpo.jax.org/app/browse/term/HP:0000006>`_. Note that if
+we type some letters into the ``HPO Term`` field, PhenoteFX will autocomplete the term if it can. 
+
+
+.. figure:: img/PhenoteAutocomplete.png
+    :scale: 50 %
+    :align: center
+    :alt: PhenoteFX - Autocomplete 
+
+
+If you hit the enter button, the term will be chosen. Then click on the ``Add annotation`` button. 
+
+
+.. figure:: img/PhenoteAnnot1.png
+    :scale: 80 %
+    :align: center
+    :alt: PhenoteFX - Autosomal dominant
+
+This adds the annotation to the curation file. The PMID is now stored as the default value and does not need to be changed unless
+you want to switch to a new citation.
+
+.. figure:: img/triphalangeal.png
+    :scale: 80 %
+    :align: center
+    :alt: PhenoteFX - Features
+
+
+We can see the clinical features to annotate in Table 1 of PMID:18178630. For instance, 11 of 12 affected 
+individuals had 
+`Triphalangeal thumb HP:0001199 <https://hpo.jax.org/app/browse/term/HP:0001199>`_.
+We can enter the frequency data as follows (and click the ``Add annotation`` button to enter the annotation).
+Note that in this case, the context of the article implies that if a ``+`` is not shown inthe table, the individual 
+did not have the feature in question. This may not always be the case and the curator should read the article to be 
+able to accurately curate the data.
+
+.. figure:: img/triphalangeal-annot.png
+    :scale: 80 %
+    :align: center
+    :alt: PhenoteFX - Annotating triphalangeal thumb
+
+
+We continue entering features in this way. The table states that five individuals had ``syndactly``. However, the text 
+states that individuals in the family had ``cutaneous/osseous syndactyly of fingers III–V or IV/V``. We do not have further
+details, and we typically curate with as much detail as possible given the data in the original publication. To search
+for a more detailed syndactyly term, we can use the HPO ontology browser on the top right of PhenoteFX.
+
+.. figure:: img/PhenoteTree.png
+    :scale: 40 %
+    :align: center
+    :alt: PhenoteFX - Ontology Browser
+
+From this, we choose the term 
+`Finger syndactyly HP:0006101 <https://hpo.jax.org/app/browse/term/HP:0006101>`_.
+
+
+
+.. figure:: img/PhenoteAnnot2.png
+    :scale: 80 %
+    :align: center
+    :alt: PhenoteFX - annotations
+
+The above figure shows the appearance of PhenoteFX after we have entered several annotations. When we are finished,
+we can use the Save or Save and Close items in the File menu to save our work (see :ref:`filemenu`).
diff --git a/docs/tutorial_create_new.rst b/docs/tutorial_create_new.rst
@@ -0,0 +1,15 @@
+.. _createnew:
+
+==================
+Create a new entry
+==================
+
+To create a new entry, use the New item from the File menu (:ref:`filemenu`). This opens a new dialog, where
+you can enter the OMIM id (just the 6-digit number)
+and the disease name (it is easiest to use copy paste for both operations). When you are done, click "OK".
+
+
+.. figure:: img/PhenoteNew.png
+    :scale: 80 %
+    :align: center
+    :alt: PhenoteFX - setup
diff --git a/docs/tutorial_file.rst b/docs/tutorial_file.rst
@@ -0,0 +1,24 @@
+.. _filemenu:
+
+===================
+PhenoteFX File Menu
+===================
+
+Use the file menu to start a new curation file, open an existing one, or save your work.
+
+
+.. figure:: img/PhenoteFileMenu.png
+    :scale: 80 %
+    :align: center
+    :alt: PhenoteFX - setup
+
+    PhenoteFX setup menu. Use it to perform the following commands.
+
+1. **New** Start a new curation file.
+2. **Open** Open an existing curation file using a standard file-system browser
+3. **Open by MIM number** If you have stored your files as OMIM:******.tab, where ****** stands for the OMIM identifier, then this command will open a file if you enter the OMIM number.
+   The command only works for files stored in the PhenoteFX default directory (see :ref:`tutorial_setup`).
+4. **Close** Close the current file. You will be asked if you want to save work if applicable.
+5. **Save & Close** Save the current file and then close it.
+6. **Save As** Save the current file using a standard system browser and optionally change the file name.
+7. **Quit PhenoteFX** Exit the app.
diff --git a/docs/tutorial_setup.rst b/docs/tutorial_setup.rst
@@ -9,7 +9,7 @@ where you would like to store the annotation files.
 
 
 .. figure:: img/PhenoteSetup.png
-    :scale: 50 %
+    :scale: 80 %
     :align: center
     :alt: PhenoteFX - setup
 
@@ -28,7 +28,5 @@ This will be the directory where you store the HPO annotation filess. Each annot
 have its own file that will be named OMIM-123456.tab (for the corresponding OMIM id).
 
 14. **Show settings**
-This item opens a window to show the current settings.
+This item opens a window to show the current settings and allows the settings entered in the previous three steps to be checked.
 
-
-The remaining menu items in the setup menu are experimental and not needed for rare disease annotation.
diff --git a/docs/tutorial_sharing.rst b/docs/tutorial_sharing.rst
@@ -0,0 +1,9 @@
+.. _sharing:
+
+======================
+Sharing curation files 
+======================
+
+The files that are created and saved in this way will be saved in the default PhenoteFX directory (see
+:ref:`tutorial_setup`). They are tab-separated text files that can be opened in Microsoft Excel if desired. 
+Share these files with the HPO team to submit new disease annotations for including the HPO resource.
diff --git a/docs/tutorial_text_mining.rst b/docs/tutorial_text_mining.rst
@@ -0,0 +1,84 @@
+.. _add_annot:
+
+===========
+Text mining
+===========
+
+PhenoteFX can also help to annotate patients one at a time starting from clinical vignettes (short descriptions).
+In the following example, we use the description of individual 1 from 
+
+
+For this example, we will use data from 
+`Wieczorek D, et al. (2010) A specific mutation in the distant sonic hedgehog (SHH) cis-regulator (ZRS) causes 
+Werner mesomelic syndrome (WMS) while complete ZRS duplications underlie Haas type polysyndactyly and preaxial polydactyly 
+(PPD) with or without triphalangeal thumb. Hum Mutat 31:81-9
+<https://pubmed.ncbi.nlm.nih.gov/19847792/>`_.
+
+
+To perform text mining, click the ``Add to cohort`` button.
+
+.. figure:: img/PhenoteTextMining1.png
+    :scale: 50 %
+    :align: center
+    :alt: PhenoteFX - text mining
+
+ now click the ``Analyze`` button.
+
+
+
+ Paste  the relevant text into the dialog that appears, click the ``Analyze`` button.
+
+.. figure:: img/PhenoteTextMining2.png
+    :scale: 50 %
+    :align: center
+    :alt: PhenoteFX - text mining
+
+Confirm the relevant findings by adding a check mark (or drag and drop to the exluded findings list below). Here, we
+have also used the browser to add the term `Tonic pupil HP:0012074 <https://hpo.jax.org/app/browse/term/HP:0012074>`_, 
+which the text mining algorithm did not pick up.
+
+.. figure:: img/PhenoteTextMining3.png
+    :scale: 50 %
+    :align: center
+    :alt: PhenoteFX - text mining
+
+
+Finally, click on ``Add selected terms`` to get the final list of terms for the current individual.
+
+.. figure:: img/PhenoteTextMining4.png
+    :scale: 50 %
+    :align: center
+    :alt: PhenoteFX - text mining
+
+
+When you are satisfied with the terms, click on the ``Confirm & close`` button.
+
+
+One or multiple individuals
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Text mining can be used for one patient or for a cohort of patients. If you use it for a cohort of 
+patients, then click on the ``Add to cohort`` button for each patient until you are done.
+
+
+Finalizing text mining
+^^^^^^^^^^^^^^^^^^^^^^
+
+To transfer the text mined results to the main PhenoteFX application, click on the ``Finish`` button.
+
+
+ .. figure:: img/PhenoteTextMining5.png
+    :scale: 80 %
+    :align: center
+    :alt: PhenoteFX - text mining
+
+Adjusting results
+^^^^^^^^^^^^^^^^^
+
+To add more information or edit a line, you can right click on many of the fields (Onset, Frequency, Sex, Pub, Evidence).
+For instance, here we have right-clicked on a frequency and could change the frequency.
+
+ .. figure:: img/PhenoteTextMining6.png
+    :scale: 40 %
+    :align: center
+    :alt: PhenoteFX - text mining