HPO Workbench Documentation

Transcription

1 HPO Workbench Documentation Release 1 Monarch Initiative Dec 10, 2018

2

3 Contents: 1 Installing and running HPO Workbench Mac OSX Windows Linux Browsing the HPO using HPO Workbench Viewing annotated diseases Using GitHub from HPO Workbench Creating GitHub issues Suggesting new annotations Generating Excel files with HPO Workbench Creating Excel files to revise or extend the HPO Using the Track Changes feature in Excel Using HPO Workbench with the latest hp.obo version Downloading the HPO github repository Building owltools Building hp.obo Using the new version of hp.obo in HPO Workbench Command-line tools Downloading HPO data Printing open issues to Word CSV Rich Text Format (RTF) Output Counting annotations HPO Workbench 13 8 GitHub repository 15 i

4 ii

5 CHAPTER 1 Installing and running HPO Workbench The following sections explain how to install HPO Workbench on Mac, Windows, and linux. The final section explains how to setup the program (the HPO data files need to be downloaded upon initial use of the program). 1.1 Mac OSX Download the latest version of HPOWorkbench.jar from HPOworkbench/releases/. You can run the program by double-clicking on this file (Prerequisite: Java version 8 or better must be installed on your Mac). You can also start the app from the command line as follows. $ java -jar HPOWorkbench.jar 1.2 Windows Download the latest version of HPOWorkbench.exe from HPOworkbench/releases/. You can run the program by double-clicking on this file (Prerequisite: Java version 8 or better must be installed on your machine). 1.3 Linux Linux users can follow the instructions given above for Macintosh. Alternatively, they can build the HPO Workbench from source. To do so, clone the GitHub repository, and build HPO Workbench using maven. $ git clone $ cd HPOworkbench $ mvn clean package This will create an executable jar file. It may be convenient to move the file to the current working directory (or someplace on the PATH). 1

6 HPO Workbench Documentation, Release 1 $ mv hpowbgui/target/hpoworkbench.jar. $ java -jar HpoWorkbench.jar 2 Chapter 1. Installing and running HPO Workbench

7 CHAPTER 2 Browsing the HPO using HPO Workbench Navigate through the hierarchy of the using the tree browser or use the autocomplete text field to find the HPO term of your choice. HPO Workbench will display the ID, definition, comment, and synyonyms for the term. If any diseases in the HPO corpus are annotated to the term, a list of the diseases will be displayed. 3

8 HPO Workbench Documentation, Release Viewing annotated diseases The diseases annotated to a given HPO term (including direct and implied annotations) can be viewed in the browser. If desired, users can limit the diseases to one of the databases, Orphanet, OMIM, or DECIPHER. To find the disease of interest, choose the radio button diseases and use the autocomplete field to find the disease, and click on the GO button. Disease annotations are arranged according to organ system. Users can navigate between Disease and HPO Term pages using the hyperlinks. 4 Chapter 2. Browsing the HPO using HPO Workbench

9 CHAPTER 3 Using GitHub from HPO Workbench GitHub is widely used by developers to manage projects together with versioning, bug reports and other issues, and many other features. We use it to host the main HPO file, and we use the GitHub issue tracker to manage suggestions. Users can post a new issue and suggest a new term or revisions to existing terms. If we have a question, we will post it as a comment to a GitHub issue (in this case, you will receive an with the text of the question and can respond to it by or by visiting the corresponding GitHub page. To use this functionality, you will need to register a GitHub name and password (which is free and easy to see up; see If you choose not to use GitHub, another way of sending us feedback is by exporting an excel file and writing your comments in this file (see the next page of this documentation). 3.1 Creating GitHub issues Users can create an issue with a suggestion for an existing term by navigating to a term they would like to comment on and clicking on the create suggestion button. Users will need to enter their GitHub username and password (which will be stored for the duration of the session, so that multiple issues can be created without having to reenter the GitHub username and password multiple times. If users would like to suggest a new term, navigate to the proposed parent of the new term, and click on suggest child term. A dialog will appear with information about the term selected by the user. Enter your suggestion in the text field. Then, enter your GitHub username and password, and and click on Create github issue. HPO Workbench will store the username and password for the duration of the session so they only need to be entered once. The data is not written to disk. 3.2 Suggesting new annotations First navigate to a disease of interest as above. This will cause the name of the disease to be shown right underneath the search window. This is now the current disease. Following this, search for the desired new annotation (HPO term) using the autocomplete field or ontology hierarchy. We can now click on the Suggest new annotation button (which turns color, acquiring a blue hue to show it was clicked). This opens up a dialog that suggests that the HPO Term For real requests of this sort it would be very 5

10 HPO Workbench Documentation, Release 1 much appreciated it you can indicate the source of the annotation (the best source is an article in PubMed - please provide the PubMed id and the title). If possible, also indicate other attributes of the annotation. What is the age of onset? What is the overall frequency of patients with the disease that have the phenotypic abnormality in question (enter 5/8, for instance, of 5 or 8 patients described in a publication were found to have the feature, but the feature was ruled out in the other 3). 6 Chapter 3. Using GitHub from HPO Workbench

11 CHAPTER 4 Generating Excel files with HPO Workbench The HPO project welcomes feedback of all kinds, and indeed the high quality of the HPO is a result of over a decade of interactions with numerous clinicians. If you have a suggestion for one or a few terms then we would prefer that you use the GitHub functionality. However, if you would prefer not to, or if you have too many terms to use GitHub, you are also welcome to send us feedback using the excel files that HPO Workbench exports. Please use the Track changes function. 4.1 Creating Excel files to revise or extend the HPO Users who would like to contribute new terms or other information to the HPO project and who would prefer to use Excel can use HPO Workbench to create an Excel file to work with. We recommend using the Create hierarchical summary option. To do so, first navigate to the area of the HPO you would like to work with (e.g., Abnormality of thyroid physiology). Clicking on the Create hierarchical summary button will create an Excel file that contains only the portion of the hpoontology that starts from this term. It will suggest the hierarchy of the hpoontology by indenting child, grandchild, great-grandchild (etc) terms in columns located further to the right ( indentation by column ). Please create a new column or columns in this file that will contain your comments and suggestions. You are welcome to contact the HPO team to get advice about this before you start (see the HPO Website for addresses). We will demonstrate the feature by exporting a small excel file that represents the HPO hierarchy emanting from the HPO Term Horizontal nystagmus. If you click on the Export hierarchical summary button, an excel file will be produced that looks something like the following Figure (we have adjusted the columns widths so that the entire contents of each column can be easily seen). We see that Horizontal nystagmus is shown as having level 1, and its child terms (e.g., Horizontal jerk nystagmus) are shown as having the next lower level (level 2). The definitions, comments, and synonyms of these terms can be seen in additional columns. 4.2 Using the Track Changes feature in Excel Many people are familiar with the Track Changes feature in Word, which shows changes to a document by coloring or otherwise highlighting changes (depending on the Word version and the user settings). Excel also has this feature, 7

12 HPO Workbench Documentation, Release 1 but the changes are not marked in quite such an obvious way. To activate the feature, go to the Tools menu and select Track changes Highlight changes... In the dialog that opens after you select this item, put a check mark in the box for Track changes while editing and apply the tracking to All changes. We see that the term Horizontal opticokinetic nystagmus currently has no definition. To demonstrate the track changes feature, we will add the text Example definition to the corresponding cell of the Excel file. The figure shows that there is now a black triangle at the upper left corner of the cell that we changed. Please make sure that all of your changes are marked in this way. If you have more comments or suggestions, please create one or more columns to hold the information you would like to enter. Add your columns directly after the final column produced by HPO Workbench. When you are finished, please send the file to the HPO team. It is highly recommended to contact the HPO team before beginning to work with Excel files for biocuration. We would be glad to check your work for one or two terms in order to ensure that all information is being faithfully transmitte4d in the Excel file before you do a lot of work. If you do not know who to contact, please consult the Team page of the Hpo Website at 8 Chapter 4. Generating Excel files with HPO Workbench

13 CHAPTER 5 Using HPO Workbench with the latest hp.obo version The hp-edit.owl file contains all of the latest changes. However, the version of the hp.obo file that HPO Workbench downloads via its Edit menu does not necessarily have the latest changes, because the later file is released on a monthly basis. To get the very latest version, it is possible to compile the hp.obo file locally and import the local file into HPO Workbench. This step requires some familiarity with the command line; if you are not familiar with this kind of work and need the latest hp.obo version, please contact the HPO team. To do so, you will need to download the HPO github repository as well as the repository for owltools. The following text assumes that you download both repositories to the same place, e.g., to some directory called GIT on your local drive. 5.1 Downloading the HPO github repository The HPO GitHub repository can be found here: Clone the repository with the following command. $ git clone Building owltools We need to download and build owltools. The GitHub repository can be found here: owltools.git. Clone the repository and build it as follows. $ git clone $ cd owltools $./build.sh 9

14 HPO Workbench Documentation, Release Building hp.obo In order to build hp.edit, we will use the Makefile located in human-phenotype-hpoontology/src/ hpoontology/. This makefile needs access to owltools. You can either add the paths to your environment (e.g., using the.bashrc file) or you can add the path to the environment of your current shell. The latter solution is shown here. $ cd src/hpoontology $ export PATH=${PATH}:../../../owltools/OWLTools-Oort/bin/:../../../owltools/OWLTools- Runner/bin/ $ make This will create a new version of hp.obo. 5.4 Using the new version of hp.obo in HPO Workbench After you have created the up-to-date version of hp.obo, import it using the Edit menu of HPO Workbench. After this, the browsing functions of HPO Workbench will use the new version of hp.obo (for the current session only). 10 Chapter 5. Using HPO Workbench with the latest hp.obo version

15 CHAPTER 6 Command-line tools HPO Workbench provides a number of command-line tools in the hpowbcli package. These are functionalities that may be included in the HPO Workbench app at a later point or in some cases are intended for working with low-level files. 6.1 Downloading HPO data Most of the commands described in this section use the hp.obo or the phenotype_annotation.tab files. The following command can be used to download both files (the default download directory is data, which can also be used by any of the following commands). $ java -jar HPOWorkbench.jar download [-d <directory>] directory is the name of directory to which HPO data will be downloaded (default: data ) 6.2 Printing open issues to Word We may want to send a summary of all open issues with our questions to our clinical collaborators in the form of a Word document. For instance, this would be the command to get a list of all issues with the label cardiovascular. $ java -jar HPOWorkbench.jar git -g cardiovascular We are using the Apache POI < Java library to create the word documents, and the overall formatting could probably be made nicer. Currently, the GitHub API seems to limit the number of issues that can be requested to 30, so this function will only work for up to 30 open issues. 11

16 HPO Workbench Documentation, Release CSV This command makes a comma-separated value file that contains all of the terms in the HPO. It is similar to the creation of an Excel file from the main app, and in the future, it will be offered as an option in the app. $ java -jar HPOWorkbench.jar csv [-h <hpo>] hpo is the path to hp.obo file 6.4 Rich Text Format (RTF) Output This function is currently not complete! We are working on an RTF output format that puts all HPO terms into an RTF table that can be imported into Word and used to make corrections using Word s track changesd tool. The RTF format is currently not tested. $ java -jar HPOWorkbench.jar rtf -h <hpo> -t <start-term> The document will start off at start-term (e.g., using a start term of Ventricular septal defect would produce a table with that term and all of its descendents). Use the HP id (e.g., HP: ). 6.5 Counting annotations The situation is that we have a list of disease annotations (which could be phenotype_annotation.tab or a smaller selection of annotations) and an HPO term. We would like to find out the total number of annotations to the term or any of its ancestors. $ java -jar HPOWorkbench.jar countfreq [-h <hpo.obo>] [-a <pheno_annot.tab>] -t <term id> 12 Chapter 6. Command-line tools

17 CHAPTER 7 HPO Workbench HPO Workbench is a Java app designed as a browser for HPO terms and annotated diseases. HPO Workbench has a series of functions that can be used by collaborators to review and make suggestions for extending, correcting, or otherwise revising the HPO or the disease annotations. HPO Workbench can be used to browser the HPO hpoontology; information about each term is shown including the definition, comments, and synonyms (if any). If the term is used to annotate diseases in the HPO database, then a list of diseases is shown. Additionally, diseases can be visualized, and all HPO terms that annotate that disease are shown according to affected system. HPO Workbench can also be used to suggest additions, corrections, or revisions to the HPO. To do this, users can navigate to the part of the HPO they would like to revise, and mark a term and suggest new child terms or other revisions. Also, new annotations for diseases can be suggested. To do so, users must enter their GitHub name and password (only once per session), and the suggestions are sent to the HPO GitHub tracker, where they will be registered under your id (so that you will get feedback via about your suggestion). HPO Workbench can also be used to export Excel files that represent the HPO hierarchy by means of indentation of columns. These excel files are meant to be used to record suggestions. Instructions for these three main use cases of HPO Workbench can be found on the following pages. 13

18 HPO Workbench Documentation, Release 1 14 Chapter 7. HPO Workbench

19 CHAPTER 8 GitHub repository The HPO Workbench GitHub repository can be found here: HPOworkbench 15