Merge pull request #34 from DeepPhe/v0.3.0

V0.3.0

Author: yuanzhou

README.md

@@ -1,4 +1,4 @@
-# DeepPhe-Viz v0.2.0
+# DeepPhe-Viz v0.3.0
 
 The DeepPhe NLP extracts information from the patient cancer reports and stores the data in Neo4j graph database. The DeepPhe-Viz tool represents the extracted information in an organized workflow to end users, enabling exploration and discovery of patient data.
 
@@ -17,12 +17,12 @@ The DeepPhe NLP extracts information from the patient cancer reports and stores
 
 You must have the following tools installed:
 
-- [Nodejs 10.13.0 (includes npm 6.4.1) or the latest LTS version](https://nodejs.org/en/download/) - which the DeepPhe-Viz tool is built upon
-- [Neo4j 3.2.x Server](https://neo4j.com/download-center/#releases) - is used to store the graph output from DeepPhe NLP
+- [Nodejs 10.15.1 (includes npm 6.4.1) or the latest LTS version](https://nodejs.org/en/download/) - which the DeepPhe-Viz tool is built upon
+- [Neo4j 3.5.x Server](https://neo4j.com/download-center/#releases) - is used to store the graph output from DeepPhe NLP
 
 if you need to manage multiple versions of NodeJS, we have been successfully using the [nvm](https://github.com/creationix/nvm) tool to configure and manage our NodeJS environment; nvm enables a user to associate a paritcular NodeJS and NPM version with their Unix shell, allowing for each switching between NodeJS versions across different projects.
 
-For neo4j server installation, we have tested the "Neo4j Community Edition 3.2.13" with this DeepPhe release, and you can download it from the [Neo4j Releases page](https://neo4j.com/download-center/#releases) by choosing the correct download for your platform. Then follow their [installation instructions](https://neo4j.com/docs/operations-manual/current/installation/) to configure and start the server.
+For neo4j server installation, we have tested the "Neo4j Community Edition 3.5.1" with this DeepPhe release, and you can download it from the [Neo4j Releases page](https://neo4j.com/download-center/#releases) by choosing the correct download for your platform. Then follow their [installation instructions](https://neo4j.com/docs/operations-manual/current/installation/) to configure and start the server.
 
 ![Neo4j server download](neo4j_server_download.png "Neo4j server download")
 
@@ -49,7 +49,7 @@ After building the [DeepPhe system](https://github.com/DeepPhe/DeepPhe-Release/b
 dbms.active_database=deepphe.db
 ````
 
-You'll also have a file named `deepphe-viz-0.2.0-plugin.zip` in the directory `deepphe-viz-neo4j/target` after building the [DeepPhe system](https://github.com/DeepPhe/DeepPhe-Release/blob/master/README.md). This compressed file contains a directory named `plugins`.  All the jar files of the `plugins` directory must be copied to `<NEO4J_HOME>/plugins` directory. The DeepPhe-Viz uses these libraries to interact with the customized DeepPhe system database.
+You'll also have a file named `deepphe-viz-0.3.0-plugin.zip` in the directory `deepphe-viz-neo4j/target` after building the [DeepPhe system](https://github.com/DeepPhe/DeepPhe-Release/blob/master/README.md). This compressed file contains a directory named `plugins`.  All the jar files of the `plugins` directory must be copied to `<NEO4J_HOME>/plugins` directory. The DeepPhe-Viz uses these libraries to interact with the customized DeepPhe system database.
 
 To run Neo4j as a console application, use:
 `./<NEO4J_HOME>/bin/neo4j console`
@@ -77,7 +77,7 @@ The Viz tool consists of two major components&mdash;cohort analysis and individu
 
 ### Cohort Analysis
 
-When we first load the DeepPhe-Viz in the web browser, you'll see a cohort analysis page. The system queries Neo4j to get all the patients of all cancer stages, and the results are represented in a series of charts.
+When we first load the DeepPhe-Viz in the web browser, you'll see a cohort analysis page. The system queries Neo4j to get all the patients of all cancer stages, and the results are represented in a series of charts. The two charts (A) and (B) on the top section can be used as filters to narrow down the target patients (C) and the resulting charts (D), (E), and (F).
 
 ![Cohort Analysis](cohort_analysis.png "Cohort Analysis")
 
@@ -87,29 +87,34 @@ This chart shows the number of patients of each cancer stage. When users click o
 
 **B. Patient Age of First Encounter Per Stage**
 
-Box-whisker plots summarizing the distribution of patient age of diagnosis across all cancer stages.
+Box-whisker plots summarizing the distribution of patient age of diagnosis across all cancer stages. The age range sliders on both sides can be used to specify the target range of first encounter age.
 
-**C. Diagnosis**
+**C. Target Patients**
 
-The diagnosis chart is a summary of all the diagnosis across all the patient or patients from the selected stage. Moving the bottom slider scrolls through the patients in the X axis.
+The target patients list is grouped by their age of first encounter and serves as the entry point to the individual patient profile. The highlighted patients are the ones being displayed in the Diagnosis chart (D).
 
-**D. Biomarkers**
+**D. Diagnosis**
 
-The biomarkers chart is a stacked bar chart that shows the percentage of patients who are positive, negative, and unknown for major biomarkers. Note - as of October 2018, this display is only meaningful for breast cancer data.
+The diagnosis chart is a summary of all the grouped diagnosis across all the target patients based on the filters. Moving the bottom slider scrolls through the patients in the X axis.
 
-**E. Patients Table**
+**E. Biomarkers Overview**
+
+The biomarkers overview chart is a simple distrubtion that shows the percentage of patients with biomarkers and patients without biomarkers among the target patients. Because biomarkers don't apply to patients with certain diagnosis.
+
+**F. Patients With Biomarkers**
+
+The biomarkers overview chart is a stacked bar chart that shows the percentage of patients who are positive, negative, and unknown for major biomarkers. 
 
-The patient table groups the target patients by their age of first encounter and serves as the entry point to the individual patient profile.
 
 ### Individual Patient Profile
 
 Clicking a target patient from the Cohort Analysis patient table, leads to display of the individual patient page.
 
 ![Individual Patient Profile](individual_patient_profile.png "Individual Patient Profile")
 
-The patient view starts with personal information on the upper left (A), followed by the cancer summary (B)  and tumor summaries (C). The default tumor summary list view stacks all the tumors and the table view shows comparable items side by side. Similar concepts are grouped and share background colors. Concepts are ordered by importance, and each can be clicked to display their original sources in clinical notes on the right. 
+The patient view starts with personal information on the upper left (A), followed by the cancer and tumor summary (B). The default tumor summary list view stacks all the tumors and the table view shows comparable items side by side. Similar concepts are grouped and share background colors. Concepts are ordered by importance, and each can be clicked to display their original sources in clinical notes on the right. 
 
-This timeline view (D) provides a temporal view of all of the reports for this patient. Currently we have the following report types:
+This timeline view (C) provides a temporal view of all of the reports for this patient. Currently we have the following report types:
 
 - Progress Note
 - Radiology Report
@@ -130,12 +135,17 @@ The double-thumb slider below the timeline  can also be used to zoom and scroll
 
 All information shown in the cohort graphs, cancer and tumor summaries, and patient timeline are extracted from clinical notes or inferred via domain rules.
 
-When you click one of the report dots, the report text is shown underneath the timeline (E) with all of the concepts extracted from the report. Clicking on these terms scauses the document text to scroll to the relevant span.
+When you click one of the report dots, the report text is shown underneath the timeline (D) with all of the concepts extracted from the report. Clicking on these terms scauses the document text to scroll to the relevant span.
 
 Note that the text in this example is obscured to protect the privacy of the patient. 
 
 All of the summary items from the full cancer and tumor summaries can also be clicked to show their source report in the timeline.
 
+## API Documentation
+
+We've created a set of API endpoints using Swagger UI for advanced users to explore the potential use cases for their additional needs. The API documentation can be accessed at http://localhost:8383/documentation once you have the DeepPhe-Viz server running. This documentation allows the users to visualize and interact with the API's resources without having any of the implementation logic in place.
+
+![Swagger API Documentation](swagger_api.png "Swagger API Documentation")
 
 ## For Developers