SPREAD, Spatiotemporal Pathogen Relationships and Epidemiological Analysis Dashboard

Description

The dashboard is based on GrapeTree is a fully interactive tree visualisation program within EnteroBase, which supports straightforward manipulations of both tree layout and metadata. It generates GrapeTree figures using the Neighbor-Joining (NJ) algorithm, Minimal Spanning Tree algorithm (MSTree), or an improved Minimal Spanning Tree algorithm called MSTree V2. The original version is an integral part of EnteroBase, and you can refer to its documentation to learn more.

For a formal description, please see the accepted manuscript in Genome Research.

The standalone version of GrapeTree has been integrated into Cohesive Information System (CIS) as the main tool for manipulating tree graphs and metadata, and it has been extended to conduct spatio-temporal analyses with an integrated geographic information system (GIS) and a time-based data visualization system. The web application allows users to upload geographic coordinates and temporal data related to each sample and display them, reflecting the selection on the tree and the map interchangeably. Additionally, it enables users to reproduce a temporal visualization both on the map and the tree.

Using SPREAD

The dashboard is integrated with the CIS platform, so you can launch analyses and view data on it. However, by directly accessing the address https://cohesive.izs.it/spread/, you can upload and visualize your own dataset.

Please note The uploaded dataset is displayed and managed exclusively client-side in the browser, which means no data is transmitted, and no tracking cookies are used. The only data downloaded from the internet is the visualization code (JavaScript), fonts, and any necessary tiles for map. Therefore, you can also upload sensitive data.

You can upload the files by dragging them directly over the initial drop area or using the upload button. You can drag or load a .nwk file followed by a .tsv file containing the metadata and optionally a .geojson file containing geospatial information related to the samples.

Important!

The .nwk file must always be uploaded before the metadata or the geoJson files.

The dashboard allows you to download a complete JSON file that includes metadata and configurations. The generated JSON file can be loaded using the same drag and drop or upload functionalities mentioned earlier, which is very useful if you want to save your work and/or share it.

grapetree-upload.mp4

Please find an example dataset on the project repository at https://github.com/genpat-it/spread/tree/main/datasets/test.

Overview of General Functions

Whether you choose to upload data from your computer or you are visualizing a pre-processed dataset from CIS Platform, you will always find yourself in the same configurable workspace. The main components that make up the dashboard along with the Tree are:

• Settings
• Map
• Legend
• Metadata
• Video

These components can be shown or hidden using the respective toggles located at the top of the main workspace, depending on your work needs. Before delving into the details of these components, let's quickly mention two functions present in the header. One is related to language change, which can be set by clicking on the globe icon, and the other, accessible by clicking on the info icon, displays useful information and links.

Available Languages and Translations

Currently, the available languages are English and Italian. However, the application can be easily extended with new translations. If you would like to contribute, you can use the en.js or it.js file as a template from the i18n folder on the public repository of the project and translate the values. For any information or support regarding this, please contact bionformatica@izs.it.

Components

Let's take a closer look at the various parts that make up the dashboard.

Settings

By activating the settings, you will enter a sort of "edit mode" and you will see a series of cards divided into thematic areas, which allow you to configure the tree. Each card can be expanded or collapsed based on your needs. Below, you will find descriptions of the various available configurations, also visible within the application by clicking on the ? icon of the respective card.

Tree layout

The Tree Layout section contains tools to modify the appearence and layout of the tree, as well as options to revert the tree to previous state and undo changes and modifications.

• Centre Tree: adjusts view settings so that the tree's core is at the centre of the working area.
• Static Redraw: refreshes the tree and redraws it with the preset layout.
• Original Tree: reloads the page and reverts the tree to the state and layout it was in when it was first loaded. It will ask for confirmation before leaving the page. Caution: this function will cause you to lose all the changes you made to the tree.

Node style

Under this category you can find options to change the node's appearance or displayed information.

• Colour by: from the dropdown menu of this section it's possible to choose the fill-in colour of the nodes according to metadata.
• Show Labels: the switch will allow you to choose whether to show the node labels or hide them. You can choose which label to show from the dropdown menu just below.
• Font Size: the font size for the labels can be chosen either by dragging the slider or by specifying a size in the box.
• Highlight Label: use the text box to provide a search term for the labels to highlight the corresponding nodes. Supports Regular Expressions.
• Individual segments: use the switch to turn each node into a pie chart showing the breakdown of the members contained in it. The breakdown is based on the category used for the Colour by settings.

Node size

• Node Size (%): the overall node size can be increased or decreased with the Node Size (%) option, either by using the slider or through the box.
• Kurtosis (%): by default the area of the nodes correlate with the members in them. Using the Kurtosis (%) section's slider or box, the node's size can be increased or decreased based on the distribution's kurtosis of the nodes. By increasing this value, you raise the percentage by which the node size grows per member in the node, thus nodes with a larger number of members will have a larger area and will stick out more.

Branch style

In this section you'll find options to customize the tree's branches.

• Show Labels: the Show Labels switch will allow you to choose whether to show the branch labels or hide them.
• Font Size: options from where the font size for the labels can be chosen by means of the slider or the box.
• Scaling (%): the main Scaling option allows you to increase or decrease the overall branches' length, by using the slider or by specifying a value in the box below the slider.
• Collapse Branches: use the slider or enter a value in the box to collapse all branches shorter than the specified length. Nodes falling in that interval will be merged together. Branch length values are scaled to the branch lengths defined in the original tree data.
• Log Scale: by checking the box, all lengths of all branches will be scaled logarithmically.

Branch cutoffs

The settings in this section will allow you to render the branches in different ways depending on their length (branch length values are scaled to the branch lengths defined in the original tree data). Use the box to enter a value. For branches longer than the specified value, it's possible to choose whether to display them, hide them, or shorten them:

• Display: show long branches as normal (default).
• Hide: makes long branches transparent. Even though the branches are not displayed, it's still possible to interact with them.
• Shorten: branches longer than the specified cutoff will be cropped back to the specified cutoff. The branches will appear as dashed lines to indicate those that are affected.

Rendering

This section contains Rendering Layout options, which control how nodes are positioned in the tree. Two modes are available: Static and Dynamic.

• Static: in Static mode, the tree layout is calculated when the tree is generated and remains static (but interactive). Relative branch length and scaling (from the original tree data) will always be maintained as long as the Real Branch Length option is checked.

• Dynamic: nodes are positioned dynamically in a way similar to a Force Directed Layout and will try to fan out in order to distance themselves from the neighbors. The tree can be moved around freely by dragging it, and the nodes will spread out to maintain the distances among themselves. The Dynamic mode can be used to improve the aesthetics of the tree, but branch length scaling will be modified. Branches will NOT be to scale when in Dynamic mode. Toggle on the Selected Only option to apply only to selected nodes.

grapetree-settings.mp4

Map

This area allows you to view an interactive map if geographic coordinates have been defined for the samples (either through metadata files or geoJSON files). On the map, markers are drawn with varying sizes based on the number of samples present in a particular area. By clicking on each marker, you can open an informative popup containing the list of samples within.

The markers reflect the colors of the chosen theme for the tree visualization and also the selection. You can interact with the map through its context menu, which can be accessed by right-clicking on the map or by using the button located at the top-right corner with three vertical dots.

Map tools

Through the options available in this section, you can control the appearance of the map.

• Join by coordinates/by metadata: The toggle allows you to aggregate points on the map based on the geographical proximity of the provided coordinates or based on the values of the loaded metadata. In the first case, you can define a numerical value for delta, which determines the degree of aggregation.
• Minimum/Maximum marker radius: With these two fields, you can adjust the size of the points on the map by defining a minimum and a maximum radius. The initial size is relative to the number of nodes present at the same geographical coordinates.
• Pie Chart mode/Heatmap mode: This toggle allows you to change the visualization mode of the points on the map. With the first option (selected by default), the points will be displayed with pie charts based on the categories of the tree nodes, while with the second option, a blur effect is applied to the nodes.

grapetree-map.mp4

Metadata

By activating the Metadata toggle, you can view the metadata within an interactive grid. The grid allows you to move columns, expand and/or reduce them, sort them, or filter them based on search keys. By clicking on a row, you can select/deselect the samples present on the tree.

Similar to the map, the metadata table also has tools that can be accessed by right-clicking on the table or by using the button located at the top-right corner with three vertical dots.

grapetree-metadata.mp4

Legend

This is a key tool for both interacting with the tree and for the temporal visualization/selection of data. Through the legend, you can change the category and color of the tree, customize the colors, or select samples from a specific category. In video mode, the legend transforms into a proper timeline.

The following video demonstrates how to access the context menu of the legend and its options, how to interact with the legend, and how to modify preferences and the color palette.

grapetree-legend.mp4

Video

The video player allows you to iterate through the legend elements at a configurable speed. The video functions are completely metadata-driven, so if temporal information is present in the metadata, you can color the legend based on that information, sort it in ascending order, and consequently have a timeline to measure the spread and development of a pathogen over time.

In the following video, you will find a possible use case.

grapetree-video.mp4

Tree

This is, of course, the main component and, therefore, always visible. It displays the tree visualization of the data and is fully interactive. You can interact with this component directly, through the context menu, or through all the other components.

You can interact directly with the tree by moving individual nodes or hovering over them to see tooltips. You can also select nodes by pressing Shift and clicking on them or drawing an area with the mouse. The selection will also be reflected in the Map and Metadata components.

TIP

To enable selection in the chart workspace, press and hold the Shift key on the keyboard. As long as the cursor appears as a crosshair, you can select or deselect individual nodes by clicking on them. You can also select multiple nodes by drawing a selection area (dragging the cursor while holding down the left mouse button).

Certainly, more interesting things can be done through the context menu or, as mentioned, through interactions with the other components (which we have discuss in their respective sections). You can access the context menu by right-clicking on the tree or by using the button at the top-right corner with three vertical dots. The menu options are quite self-explanatory, and we invite you to try them out to better understand their functionality through interaction.

In particular, we will focus on the save functions here.

Save SPREAD

Through Save SPREAD button you will have access to a modal that allows you to save and/or export SPREAD in various formats:

• Save as complete json (.json): Allows you to save the current work in a complete .json file containing all the information about the tree object, its metadata, and the current configurations of the different components. This functionality is crucial, as it is the only way to save your progress in editing SPREAD, resume it at a later time, or share it with others. The .json file stores information such as node placement and color, current category, node visualization modes on the map, workspace layout configuration, and even which settings cards are expanded or collapsed.
• Export newick (.nwk): Exports data in the .nwk format.
• Export metadata (.tsv): Exports metadata in the .tsv format.
• Export geoJson (.geoJson): Exports the spatial metadata in the .geojson format.

All the files produced are compatible to be reloaded later in the dashboard, as mentioned in Using SPREAD.

grapetree-tree.mp4