-
Notifications
You must be signed in to change notification settings - Fork 0
Home
TreeN93 is an entirely web-based tool; it is a static website hosted on GitHub Pages, written using JavaScript and HTML. TreeN93 consists of two parts: Build and Viz. Build is used to construct a tree from pairwise distances between sequences, and Viz is used to visualize a tree and its clusters at various distance thresholds. In both parts of TreeN93, the tree is created and stored using Phylotree.js.
The Build portion of the tool is used to create a Newick-formatted single-linkage hierarchical clustering tree from a collection of pairwise distances between sequences. The Newick string created by Build can, after being downloaded by the user, be used as an input for the Viz portion of the tool. Build has an amortized linear time complexity with respect to the number of pairwise distances, meaning it scales roughly quadratically with the number of sequences if all pairwise distances are provided.
The pairwise distances must be inputted as a CSV file, and they can be formatted either as a list or a matrix.
An example list might look like:
A,B,1
A,C,2
A,D,3
B,C,2
B,D,3
C,D,3
An example matrix might look like:
,A,B,C,D
A,0,1,2,3
B,1,0,2,3
C,2,2,0,3
D,3,3,3,0
From the inputted pairwise distances, Build constructs the tree and creates a Newick string representation the user can save as a .txt file.
An example Newick string might look like (((A:1,B:1)1:1,C:2)2:1,D:3)3
The Viz portion of the tool is used to view the tree and its clusters at various distance thresholds. Visualizing the tree topology is itself useful because it allows the user to see whether there are any clear gaps between groups of individuals. This tool also allows the user to select any clustering threshold and view the resulting HIV-TRACE clusters at that chosen threshold directly on the tree.
The input for Viz is a Newick file containing an ultrametric single-linkage clustering tree with unique leaf labels. It should be noted that a clustering tree (such as one constructed by TreeN93 Build) is distinct from a phylogeny.
There are several ways for the user to select a threshold. The first is a text input box in which the user can enter any number between 0 and the height of the tree. The next method is a range slider, located directly below the text input box, which is bound by 0 and the height of the tree. Additionally, the user can click on any node in the tree, bringing up a menu that shows the height of the selected node and has a button to snap the threshold exactly to that node’s height. Finally, there is a button labeled “maximize” which, when clicked, calculates and sets the threshold to the minimum threshold that yields the maximum number of non-singleton clusters (i.e., clusters containing at least 2 individuals).
Any time the threshold is changed, the clusters on the tree are recalculated. After the clusters are calculated, the visualization of the tree updates automatically to reflect the new clusters. The clusters are differentiated using color; the leaves and branches in a cluster are all filled the same color. Viz uses four distinct colors, and it ensures that all directly-adjacent clusters are colored differently. All branches whose source node is not part of a cluster are colored light gray. The current transmission clustering can be saved in the text format used by HIV-TRACE’s tn93 tool. Alternatively, the colored visualization of the tree and its clusters can be exported raster (PNG) or vector (SVG) image file.
There are a few other features in the Viz tool to increase ease of navigation of the tree. In the top left corner of the webpage, there is a guide tree. The guide tree provides an overview of the entire tree, shrunk down to fit within a 400x400 pixel square. On the guide tree, there is a vertical red line indicating where the threshold is set, as well as a gray rectangle showing which part of the larger tree is currently visible in the browser window. If the user clicks anywhere within the guide tree box, the browser window will automatically scroll to display the clicked-on region of the tree. Additionally, there are buttons to expand and compress the tree in both the x and y directions, as well as buttons to vertically flip the tree.