Getting Started with VERTEX

Introduction

VERTEX (Visual Evidence & Research Tool for Exploration) is a web-based application that presents graphs and tables relating to research questions that need to be quickly answered during an outbreak. This helps identification of key epidemiological factors and facilitates data-driven decision-making.

VERTEX is built using blocks of code, which we call reproducible analytical pipelines (RAPs). RAPs are used to create visualisations, graphs and tables, each of which we call an insight. Insights are grouped together in an insight panel to provide information about one study endpoint relating to a particular research question. You will learn more about RAPs and insight panels in this guide and in the following VERTEX guides.

At the moment, we have insight panels for the following research questions:

What are the characteristics and clinical presentation of patients with ... at hospital admission?
What are the outcomes within ... days of presentation, and what are the risk factors associated with these outcomes?
What treatments are administered to patients with ... during their observation period?

New questions will be added by the ISARIC team and the wider scientific community, enabling the creation and sharing of new RAPs and insight panels.

This guide will help you set up a VERTEX dashboard on your local machine, and explore the existing pipelines.

Automatic Installation

Download and run the installer file VERTEX_Win_AutoInstaller.exe in any location on your computer. Wait for a terminal window to open, and a sequence of commands will execute. The installation process takes about 10 minutes. You don't need to keep the window maximized (it can be minimized while the process runs).

Possible issues:

If the window closes instantly or within the first few seconds of execution, click again to run the installer.
If the page remains static on "Info", do not close the window, as the installation has not finished yet.
If you are working with VS Code, you will need to change the Python compiler to the pyenv compiler (always the latest version).

Manual Installation

Cloning the repository

First, clone the VERTEX GitHub repository. If you have git already installed then, at the command line:

git clone https://github.com/ISARICResearch/VERTEX.git

You can also download the repository manually, by clicking on the green button "Code" in the VERTEX GitHub repository, then on "Download ZIP".

This will create a local version of the repository on your machine.

If you used git, this repository will be in your current working directory, named VERTEX. Navigate to the repository, at the command line:

cd VERTEX

If you downloaded the repository manually, this repository will be in your Downloads folder, named VERTEX-main. Click into this folder.

VERTEX is a tool based on Python code. Please ensure you have Python installed on your machine. You can check which version of Python you currently have installed, at the command line:

python --version

Install the dependencies using the requirements.txt file. If you are currently working on several projects, you may want to create a new environment for VERTEX. You may want to use environment management software such as Docker or Conda.

python3 -m pip install -r requirements.txt

Modifying the config file

If you want VERTEX to run using a REDCap database, you need to modify the file called redcap_config.py to include your REDCap API token. The API token currently in this file is for a small low-fidelity synthetic dataset (fake data) hosted in an ISARIC REDCap project.

If your database contains real patient data, then is vitally important that you do not share this API token, as others may be able to access your data if you do so. The easiest way to avoid this scenario is if you do not share your version of the redcap_config.py, once you've updated this.

You should also change the REDCap url to your institution's REDCap URL and provide site codes for all sites in your database. VERTEX currently assumes the subject IDs are formatted as xxxxx-yyyyy where xxxxx is the site code listed and yyyyy is the patient number for that site, as ISARIC standard procedure.

If this is not the case for your REDCap project, or if you do not know how to access the details needed for the config file, then please get in touch at data@isaric.org and we will help you to modify this.

redcap_api_key='BCC83FD05676798456262ED4883FD85C'
redcap_url='https://ncov.medsci.ox.ac.uk/api/'
site_mapping={'00000':'COL',
              '00001':'GBR',
              '00002':'CAN',
              '00003':'KEN',
              '00004':'FRA',
              '00005':'POL',
              '00006':'UGA',
              '00007':'RWA',
              '00008':'BRA',
              '00009':'NLD'}

Running the dashboard script

After the installation of VERTEX is complete, open a terminal or a code editor and run the following command. If you have downloaded VERTEX manually, you should run this from within the VERTEX repository.

descriptive_dashboard.py

The VERTEX dashboard will now be running. The program will print output including the following: Dash is running on http://xxx.x.x.x:xxxx/, where each x is replaced by a number. The default URL is http://127.0.0.1:8050. Copy this http address into your web browser to open the dashboard.

VERTEX dashboard

The VERTEX dashboard is an interactive map with a menu for accessing insight panels. The first item in the menu is Filters and Controls, which can be used to filter the displayed data according to Gender, Age, Outcome, and Country (A). Each of the other items in the menu represents on a key research question (B). Within an item, there are items for each study endpoint associated with this research question. Clicking on one of these items will bring up the insight panel for this endpoint. Countries with patients in the data is highlighted on the map, with the colour indicating how many patients are from each country (C).

Insight panels

Insight panels show visualisations relevant to a particular study endpoint. An insight panel contains another Filters and Controls setting (D), a list of all insights for the endpoint (E), a visualisation or table for the selected insight (F), and About and Instructions buttons for further information (G).

Next steps

For a more detailed guide in writing new reproducible analytic pipelines (RAPs) for VERTEX, please refer to the insight panel guide.

Home

Contents