Skip to content
Visualization of electronic medical records or other sequence event data.
Python JavaScript HTML Shell CSS
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.


Type Name Latest commit message Commit time
Failed to load latest commit information.
feature_extraction improved whitelist iteration Jun 28, 2015
js fix Oct 16, 2015
lib update submodules Feb 2, 2016
pub add presentation Apr 13, 2016
test read visits Oct 19, 2015
.gitattributes manually set filetype of python scripts May 17, 2015
.gitignore some cleanup Mar 8, 2019
.gitmodules make server for transparently changing to a dynamic system Oct 13, 2015
.travis.yml revert upgrading some packages Oct 16, 2015
LICENSE add MIT license Feb 16, 2015 revert some of the changes Mar 8, 2019 remove shebangs May 17, 2015 updating shebang May 31, 2015 fix loading problem Oct 14, 2015 avoid renaming global symbols Mar 8, 2019 clean up Oct 20, 2015
config_omop.txt example cdm/omop config file Oct 19, 2015
config_shelve.txt deidentify fs Oct 18, 2015
favicon.ico make server for transparently changing to a dynamic system Oct 13, 2015
format.json deidentify fs Oct 18, 2015
format_shelve.json deidentify fs Oct 18, 2015 updating shebang May 31, 2015
index.html no slow mode Oct 17, 2015
inspect.html update loading path for images Jun 23, 2015 remove tabs Mar 8, 2019 updating shebang May 31, 2015
overview.png update overview figure Mar 12, 2015
pca.html lasso selection in pca Jun 26, 2015 avoid renaming global symbols Mar 8, 2019 more info about db cache Mar 8, 2019
requirements.txt optionally install psycopg2 Oct 15, 2015 remove tabs Mar 8, 2019 update NDC URL Mar 25, 2018 deidentify fs Oct 18, 2015 avoid renaming global symbols Mar 8, 2019 deidentify fs Oct 18, 2015 updating shebang May 31, 2015
style.css fingerprints (kind-of) May 12, 2015
style_classes.json read visits Oct 19, 2015
text.html update loading path for images Jun 23, 2015 fix dirty bug Oct 21, 2015


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.

You can’t perform that action at this time.