HPO Workbench

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).

Mac OSX

Download the latest version of HPOWorkbench.jar from https://github.com/TheJacksonLaboratory/HPOworkbench/releases/. You can run the program by double-clicking on this file (Prerequisite: Java version 16 or higher must be installed on your Mac). You can also start the app from the command line as follows.

$ java -jar HPOWorkbench.jar

Windows

Download the latest version of HPOWorkbench.exe from https://github.com/TheJacksonLaboratory/HPOworkbench/releases/. You can run the program by double-clicking on this file (Prerequisite: Java version 16 or higher must be installed on your machine).

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 https://github.com/TheJacksonLaboratory/HPOworkbench.git
$ 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).

$ mv hpowbgui/target/HpoWorkbench.jar .
$ java -jar HpoWorkbench.jar

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.

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 email 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).

HPO Workbench - exported excel file

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.

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, 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.

Excel - activate track changes feature

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.

Excel - Appearance of tracked changes

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 https://www.human-phenotype-hpoOntology.org.

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.

Downloading the HPO github repository

The HPO GitHub repository can be found here: https://github.com/obophenotype/human-phenotype-hpoOntology. Clone the repository with the following command.

$ git clone https://github.com/obophenotype/human-phenotype-hpoOntology

Building owltools

We need to download and build owltools. The GitHub repository can be found here: https://github.com/owlcollab/owltools.git. Clone the repository and build it as follows.

$ git clone https://github.com/owlcollab/owltools.git
$ cd owltools
$ ./build.sh

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.

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.

HPO Workbench - import local hp.obo

After this, the browsing functions of HPO Workbench will use the new version of hp.obo (for the current session only).

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.

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”)

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 <https://poi.apache.org/> 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.

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

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:0000123).

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>

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 Email 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.

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.

HPO Workbench - browsing

GitHub repository

The HPO Workbench GitHub repository can be found here: https://github.com/TheJacksonLaboratory/HPOworkbench