Skip to main content

Run the DeepPhe Workflow

Run the buttons from left to right for a complete local workflow.

1. Confirm Project Settings​

Before starting a run, check:

  • The Piper file exists and matches the pipeline you want.
  • The corpus directory contains patient directories and readable documents.
  • The OMOP database path points to the demographics JSON file.
  • The output directory is writable and has enough disk space.

2. Run the NLP Summarizer​

Click NLP Summarizer.

The Desktop GUI writes a small CLI parameter file for the selected project, then starts the DeepPhe NLP Piper File Submitter with the selected Piper file. The command is equivalent to:

bin/runDeepPheGUI -p <PIPER_FILE> -c <PROJECT_NAME>.cli

The generated CLI file contains:

InputDirectory=<CORPUS_DIR>
OutputDirectory=<OUTPUT_DIR>

Progress and errors appear in the Desktop Activity Log. Detailed tool output is written to the DeepPhe log directory.

3. Run the Data Merge Tool​

Click Data Merge Tool.

This step combines the NLP output with the OMOP demographics JSON and prepares data for visualization. The GUI passes three arguments to the merge tool, with a command equivalent to:

runDbCreator <OUTPUT_DIR> <OMOP_DB> <OUTPUT_DIR>/vizDb/<PROJECT_NAME>

Wait for the activity log to report that the merge completed successfully before starting the visualizer.

4. Start the Visualization GUI​

Click Visualizer Startup.

The GUI starts two local services:

ServiceURLPurpose
DeepPhe Data APIhttp://127.0.0.1:3333Serves the visualization database.
DeepPhe Visualizerhttp://127.0.0.1:3334Browser-based cohort and patient interface.

After both services pass their health checks, the GUI opens:

http://127.0.0.1:3334

5. Shut Down the Visualizer​

When the visualizer is running, the Desktop GUI button label changes to Visualizer Shutdown. Click it before exiting if you want to stop the local Data API and visualizer immediately.

The Desktop GUI also tries to stop visualization services when the desktop app exits.

The visualizer uses local ports only. It does not publish patient data to the public internet, but you should still follow your institution's rules for handling clinical text and derived data on the workstation.