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.

VERTEX is built using blocks of code, which we call reproducible analytical pipelines (RAPs). RAPs create a dataframe that can be used for graphs and tables, each of which we call visuals. Visuals are grouped together in an insight panel to provide information about one clinical measure related to a research question.

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 to create a new insight panel. These are practical instructions for how to adapt the VERTEX code only. Before you start, you should consider how you want to present or the model the data.

Reproducible analytical pipelines

Reproducible analytical pipelines (RAPs) are built using small reusable modular blocks of code. These blocks of code process the database into an analysis-ready dataframe for a clinical measure relating to a research question. This dataframe can then be used to create a visual, i.e. a table or figure.

RAPs automate the process of data analysis ensuring results are consistent, transparent, and reproducible. They can be reused across different analyses with easy adjustments without modifying the core code.

Getting started with VERTEX

For this guide, you will need your own local copy of VERTEX. If you have not already done so, please follow the VERTEX starting guide: https://isaricresearch.github.io/Training/vertex_starting.

In order for VERTEX to work with data from your own REDCap project, you need to modify the config file to include your REDCap API token. 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. Please see the VERTEX starting guide for more details about this.

Core scripts in VERTEX

The core scripts in VERTEX are:

• getREDCapData.py: this script imports data from a REDCap project via an API token, gets the data type for each variable and reformats the dataframe
• IsaricAnalytics.py: this script contains reusable modular blocks of code used in the standard RAPs, e.g. converting data to the same units, imputing missing data, fitting models
• IsaricDraw.py: this script contains functions for converting dataframes into insights e.g. visualisations, tables and figures
• descriptive_dashboard.py: this script is the main function for the web-based application, which runs the dashboard and defines what happens when the user interacts with the dashboard

You will not need to modify these scripts, but you may choose to do so if you want to customise VERTEX. Please only attempt this if you are confident programming and please contact us at data@isaric.org for more support.

Insight panels

Each insight panel should have a separate .py in the folder insight_panels. In order to create a new insight panel, you will need to create a new script in this folder. If you want to add multiple insight panels to your copy of VERTEX, each one will need its own script.

An insight panel script must contain several components that are required by the main dashboard script. These should be structured identically in each insight panel script.

This guide will describe the template insight panel, Examples_Generic.py. You can copy or adapt this script to create a new insight panel. You can also explore the other insight panels to gain familiarity with how an insight panel script is structured.

Examples_Generic.py

STEP 1: Rename the script

We recommend the script for an insight panel to be named xxxx_yyyy.py, where you have replaced xxxx with the research question and yyyy with the clinical measure, e.g. ClinicalPresentation_DemographicsComorbidities.py.

STEP 2: Add the name of the script to __init__.py

The insight_panels folder has an __init__.py file, which contains a list of the insight panels that will appear in the dashboard (__all__). You must add the new insight panel name (without .py at the end) to this list for it to be included in the dashboard.

You can also add or remove any insight panel script names to this list before running the dashboard, in order to customise which are included in the VERTEX dashboard.

The __init__.py script does not need to contain all of the insight panels in the insight_panels folder, only the ones that you currently want to include in your dashboard. If you do not want to an insight panel in the folder to appear in the VERTEX dashboard, then you should leave its script in the folder and just remove the name of the script from __init__.py.

STEP 3: Change the suffix variable

Next, you should change the suffix variable at the beginning of the script. Each insight panel script in your copy of VERTEX must have a unique suffix.

Elements of the VERTEX dashboard (e.g. callbacks) are identified in part by this suffix variable, so VERTEX needs to distinguish between the same callback from two different insight panel scripts.

You should also change the research_question and clinical_measure variables. These correspond to the research question (A) and the insight panel label (B) that appear in the VERTEX menu.

Multiple insight panels can share the same research question, and these will be grouped together in the dashboard menu. However, the combination of research question and clinical measure must be unique.

STEP 4: Create visuals

The next part of the code you will need to modify is the function called create_visuals. In Examples_Generic.py, this creates two placeholder figures for the insight panel, which are both simple scatter plots. The output of this function is a list of all figures that you want to include in the insight panel.

def create_visuals(df_map):
    '''
    Create all visuals in the insight panel from the RAP dataframe
    '''
    # dd = getRC.getDataDictionary(redcap_url, redcap_api_key)
    # # variable_dict is a dictionary of lists according to variable type, which
    # # are: 'binary', 'date', 'number', 'freeText', 'units', 'categorical'
    # variable_dict = getRC.getVariableType(dd)

    fig1 = idw.fig_placeholder(
        df_map,
        graph_id='fig1_id' + suffix, graph_label='Figure 1', graph_about='')
    fig2 = idw.fig_placeholder(
        df_map,
        graph_id='fig2_id' + suffix, graph_label='Figure 2', graph_about='')
    return fig1, fig2

The first part of this function is commented out as it is not needed for this insight panel, but it would return the data dictionary and a dictionary of variable lists by type, which are often useful for this function.

The visuals are created via the core script IsaricDraw.py, which was imported at the beginning of the script as: import IsaricDraw as idw.

Each visual from IsaricDraw.py must input one or more dataframes and the keyword arguments graph_id, graph_label and graph_about:

• graph_id is an identifier for the dashboard, so must be unique.
• graph_label is the name of the visual in the insight panel (E).
• graph_about is information for a dashboard about the plot, e.g. a figure caption. This will be included in the About section (G).

Some visuals may have additional keyword arguments, e.g. for color schemes.

You do not need to edit the Filters and Controls setting (D), which is the same for all insight panels and is therefore generated in IsaricDraw.py.

STEP 5 (optional): Modify the data processing, modal creation, callbacks

You may choose to modify any other sections of the insight panel script, but this is not required and not recommended unless you are confident programming.

Visuals in IsaricDraw.py

STEP 6 (optional): Add new RAPs and/or visualisations

Visualisations in an insight panel are created in the core script IsaricDraw.py.

VERTEX uses a Python library called Plotly for displaying tables and figures, and this script already contains a number of useful Plotly graphics. More details about the standard Plotly graphics is available can be found at https://plotly.com/python/.

If you want to create a figure type that isn't currently available in VERTEX, you will need to add a new function to IsaricDraw.py, in the same structure as the example below.

def fig_placeholder(df, graph_id='table', graph_label='', graph_about=''):
    x = [1, 2, 3, 4, 5]
    y = [10, 14, 12, 15, 13]
    fig = go.Figure(data=go.Scatter(
        x=x, y=y, mode='markers', marker=dict(size=10, color='blue')))
    fig.update_layout(
        title='Sample Scatter Plot',
        xaxis_title='X Axis',
        yaxis_title='Y Axis')
    graph = dcc.Graph(
        id=graph_id,
        figure=fig)
    return graph, graph_label, graph_about

Input arguments for this function were mentioned earlier in the guide. The function must return a Dash object containing the figure and graph_id as Dash attribute id. It must also return the inputs graph_label and graph_about as outputs.

Notice that the placeholder figure here doesn't require use the input dataframe, but it was still included as an input.

Support and feedback

VERTEX is still a work in progress and we will updating this guide as we make improvements.

Please get in touch with us at data@isaric.org if you have any questions or suggestions about VERTEX or about the training guides and we will be happy to help!