Quick Start - DeepPhe/DeepPhe-Release GitHub Wiki

Quick Start for Cancer DeepPhe project, v0.3

Prerequisites

You must have the following tools installed to build this project:

The following tools are recommended

  • IntelliJ IDE is suggested to run the pipeline
  • Eclipse is another IDE that can be used to run the pipeline

Note: You cannot run the DeepPhe pipeline and the Neo4j server at the same time.

To run a pipeline you must make sure that you stop the neo4j server.

Obtaining the code

Please let us know if you download the code, even for a look, by posting to the DeepPhe group. Metrics on downloads and usage could help us with funding future enhancements.

There are several methods that can be used to obtain the DeepPhe code from GitHub. The three most common are:

  1. Download a Zip file from GitHub using a browser
    1. Download the Zip File
    2. Unzip the file
  2. Clone using Git 
    git clone https://github.com/DeepPhe/DeepPhe-Release.git
  3. Checkout using Subversion 
    svn co https://github.com/DeepPhe/DeepPhe-Release.git

Note: If you are in a Private Network or using a Virtual Machine, you may have problems with access to certain internet locations. Please see your System Administrator to gain access to trusted sites or enable network ports.

Please drop us a note if you obtain the code, by posting to the DeepPhe group. Metrics on downloads and usage could help us with funding future enhancements.

DeepPhe file structure

The DeepPhe root directory deepphe-0.3.0/ contains four Maven modules:

  1. deepphe-ctakes-cancer
  2. deepphe-distribution
    • Code and resources to create a binary installation
  3. deepphe-fhir
    • Code and resources to perform Document and Phenotype summarization
  4. deepphe-uima
    • Code and resources to perform Document and Phenotype summarization

There is also a data/ directory with subdirectories containing:

  1. pipeline/
  2. sample/reports/patientX/
    • three example notes for a fictional patientX
  3. sample/output/patientX/
    • sample system output for the fictional patientX
  4. sample/gold/patientX/
    • sample gold annotations for the fictional patientX
  5. sample/scores/patientX/
    • sample score summaries for the fictional patientX

The resources directory contains the DeepPhe ontology data.

Running the DeepPhe software with Maven

Graphical User Interface (GUI)

The system can be run by using a GUI from Apache cTAKES™.

The GUI can be launched using a Maven Profile.

The profile is named 'startGui' and will start with default settings to run notes for patientX. These settings include:

  • Input Directory (with Notes/Reports) *
  • Output Directory (for neo4j database and summary files) *

The GUI will allow you to load different pipelines, load and save custom pipeline parameters, and run pipelines. See Piper File Submitter GUI for more information.

The 'startGui' Profile can be run from the command line:

mvn compile -PstartGui

or using an IDE with Maven integration such as IntelliJ

To run the Profile within IntelliJ

  1. Open the Maven Projects tool window.
  2. Import the maven projects if IntelliJ did not automatically import them. (you can use Reimport Maven Projects within the Maven Projects tool window).
  3. Open the list of Profiles within the Maven Projects tool window.
  4. Ensure runJcasGen is selected.
  5. Ensure startGui is selected.
  6. Open Lifecycle under deepphe (root) and start "compile" (e.g. by double clicking).

Running the DeepPhe software using a command line

Building the binary Installation

To more easily distribute the application to other machines that do not have the necessary developer environment, you can build a binary installation.

  1. Build the a binary Installation

    mvn clean package -Dmaven.test.skip=true

    This will create a file named deepphe-0.3.0-bin.zip in the directory deepphe-distribution/target. This will also create a file named deepphe-viz-0.3.0-plugin.zip in the directory deepphe-viz-neo4j/target, a file that is not necessary for the core the DeepPhe system but is necessary to view data with DeepPhe Viz.

  2. Copy the deepphe-0.3.0-bin.zip zip file to any directory and unzip it. Unzipping the file may take several minutes.

    After unzipping, you will have a directory named deepphe-0.3.0-bin and within that directory another named deepphe-0.3.0. On some system configurations the parent directory deepphe-0.3.0-bin will not exist, only the directory deepphe-0.3.0.

Running the binary Installation

  1. Open a command line.
  2. Change directory to the bin directory within deepphe-0.3.0.
  3. To run the GUI using a script execute:
sh startDeepPhe.sh

or (for Windows):

startDeepPhe.bat

To run the GUI directly using java, execute (within directory deepphe-0.3.0):

java -Xmx3G -cp lib\*;resources\ org.apache.ctakes.gui.pipeline.PiperRunnerGui -p data\pipeline\DeepPhe.piper

Note: The GUI can only run a pipeline once. To run the DeepPhe pipeline a second time you must restart the GUI.

You can also run DeepPhe directly, without a GUI using java (within directory deepphe-0.3.0):

java -Xmx3G -cp lib\*;resources\ org.apache.ctakes.core.pipeline.PiperFileRunner -p data\pipeline\DeepPhe.piper -i <yourInputDir> -o <yourOutputDir>

Note: The java commands above use Windows format backslash \ and ;. For unix systems substitute forward slash / and : respectively.

View data with DeepPhe Viz

After building the binary installation you have a file named deepphe-viz-0.3.0-plugin.zip in the directory deepphe-viz-neo4j/target. This compressed file contains a directory named plugins. The contents of the plugins directory must be copied to your Neo4j 3.5.x plugins directory. Neo4j 3.5.x uses these libraries in NEO4J_HOME/plugins to interact with the customized DeepPhe system database.

For information on installing and running the DeepPhe Viz tool, please visit DeepPhe Viz.

After running the pipeline there is a output_graph/deepphe.db directory generated in your selected Output Directory.

Note: Existing files in the output_graph directory are overwritten when DeepPhe is run with the same Output Directory.

Be sure to make a copy of an existing graph if you wish to keep it.

Note: You cannot run the DeepPhe pipeline and the Neo4j server at the same time.

To run a pipeline you must make sure that you stop the neo4j server.

Note: Because of Neo4j version differences, you must use a version of Neo4j in the 3.5.x family. Any version of Neo4j outside the 3.5.x range will not work with DeepPhe version 0.3.0.

More Documentation