Skip to content


Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


patient-viz is a tool allowing to view and explore electronic medical records or other time sequence event data. The web-based tool is mostly written in d3 and uses python and shell on the back-end. Example data from medical insurance claim data can be downloaded automatically. We also have a live demo! The project is a joint product of Josua Krause, Narges Sharif Razavian, Enrico Bertini, and David Sontag. A short description of how to read the visualization can be found in the PDFs linked in the publications section.

The tool in action!

Build Status


Setting up the project can be done without prerequisites on MacOS and linux. For windows you need to install git and python and use git BASH to execute shell commands.

patient-viz supports four data formats as input:

  • OMOP Common Data Model: A PostgreSQL based data model. Instructions for setting up the connection can be found here.

  • CMS Data Model: A tabular data model in CSV files. Example data is openly available. Instructions on how to set up the tool for CMS data and how to download example data can be found here.

  • Shelve DB: A faster wrapper for CMS data. Instructions can be found here.

  • JSON input files. Directly access JSON files using the URL http://localhost:8000/patient-viz/?p=json/ABC.json&d=json/DEF.json where json/ABC.json and json/DEF.json are respectively events and dictionary JSON files as specified here. A python -m SimpleHTTPServer server needs to be running in the parent dictionary.

OMOP Common Data Model

patient-viz can connect to PostgreSQL databases in the OMOP Common Data Model. In order to do so you can use the following commands (assuming a fresh clone of the repository):

./ --default-omop


./ --default-omop --apt

if apt-get is available on your system. On MacOS the installation of the dependency psycopg2 may fail. In this case please refer to the psycopg installation guide.

Note: Dependency installation may require sudo rights and will prompt as needed. Do not run with sudo.

You will be prompted questions to configure the connection to the PostgreSQL database containing the data. Using the external CCS hierarchy and caching are recommended options that allow for a richer and smoother user experience.

After successfully configuring the connection you can run


to start the visualization server. Please refer to ./ -h for command line arguments. With the default command line arguments (ie. none) you can now browse http://localhost:8080/patient-viz/ (Note that patient-viz in the URL depends on the name of the folder that contains

If you want to inspect a certain patient you can browse to the corresponding id directly. For example, to show the patient with the person_id 1234 as found in the person table you can browse:


You can also use the person_source_value using a different notation. The patient with the person_source_value of 12345678 can be found at:


(Note the .json after the id)

If you prefer to not cache patient files edit config.txt (or the config file you are using) to set "use_cache": false. patient-viz cannot automatically detect changes to the database content. When using caching you can force the patient files to update by removing the corresponding files in the json folder (the json folder can be safely removed to clear all cached patient files) and the patients.txt file (this file only contains a small subset of patient ids in the database; other patients can be accessed via specifying the URL as described above; once a patient file has been cached it will show up in the patient list regardless of the content of patients.txt). The dictionary.json file contains the mappings for readable code names; if those mappings change the file needs to be removed when using caching.

If you want to stop the server you can type quit into its console (CTRL-C might affect the terminal which can be fixed by running reset). Type help for available server commands.

Updating the git repository to the newest version found on Github should be done via ./ --update as it cleans the cache and updates dependencies as well.



Pull requests are highly appreciated :) Also, feel free to open issues for any questions or bugs you may encounter.


Visualization of electronic medical records or other sequence event data.







No releases published


No packages published