Overview Examples API Source

TnT Tree

Visualization of trees for the web

#Introduction

TnT Tree is a javascript library for displaying trees in the web. It is part of the the TnT set of visualisation libraries to display trees and track-based visualisations. It has been designed with a powerful API, written with flexibility in mind, that allows the creation of expressive, dynamic, interactive and powerful tree visualizations.

TnT Tree includes several elements to facilitate the creation, manipulation and configuration of trees: a tree display that defines several properties of the visualisation including layouts, labels and node displays, a library to manipulate nodes at the data level and methods to load the trees in newick or nhx format.

Tree Visualisation

In TnT Tree, a tree visualisation is composed of several elements: a layout that defines the shape of the tree (either radial or vertical), node displays that define how each node is rendered and labels that specify how the labels are defined in the final visualisation. Each of these elements can be configured independently and useful default values are provided. In the final tree, new nodes can be added or removed dynamically and the tree updated. All the methods available to configure each element are fully explained in the API documentation.

Nodes

In TnT Tree incorporates several methods for tree manipulation including a functional interface for traversing the tree, searching nodes, applying callbacks, collapsing parts of the tree, selecting subtrees or calculating the lowest common ancestor of a set of nodes, for example. Once the tree has loaded its data, it is possible to get the root node by calling its root method. Check the Node API documentation for a full list of methods available for nodes.

Input trees

Trees can be loaded in TnT Tree using its data method. The format for this input tree is a nested object in which each object (node) has a children property whose value is an array of objects (children nodes in the tree). The terminal objects don't have the children property. This is a simple example of tree object:

var jsonObj = {
    "name" : "root",
    "children" : [
        {
            "name" : "leaf1"
        },
        {
            "name" : "leaf2"
        }
    ]
};

Because it it not particularly easy to define trees this way, TnT Tree offers tnt.tree.parse_newick and tnt.tree.parse_nhx, two methods that can read a newick or nhx string respectively and converts it into the structure shown above. When the input is a newick/nhx tree, the returned object has its name property set to the name of the node. If branch lengths are provided the branch_length property is used.

#Example

Examples are a fundamental part of TnT Tree documentation. Check more in the examples page

// Input tree
var newick = '((human, chimp),mouse)';
var treeObj = tnt.tree.parse_newick(newick);

// Tree visualisation configuration
var tree = tnt.tree()
    .data(treeObj)
    .layout (tnt.tree.layout.vertical()
        .width (650)
        .scale(false)
    )
    .node_display (tnt.tree.node_display.circle()
        .size(5)
        .fill(function (node) {
            if (node.is_leaf()) {
                return "blue";
            }
            return "green";
        })
    )
    .label (tnt.tree.label.text()
        .height(30)
        .text (function (node) {
            return node.property("name");
        })
    );

// Tree rendering
tree (document.getElementById("divId"));

The example above starts by creating a new tree object from a newick string using tnt.tree.parse_newick. It then creates a new tree visualisation passing the tree object as its data. The layout of the tree, the nodes aspect and the labels for the tree visualisation are also configured. Finally, the tree visualisation is rendered using the div element passed as its argument.

The tree visualisation is a function itself that when executed initialises the visualisation using the provided DOM element as its DOM container. It is important to understand these two states of the visualisation:

#Installation

TnT Tree can be linked directly from the github repo. It depends on the D3js library and this needs to be linked before TnT Tree

<link rel="stylesheet" href="http://tntvis.github.io/tnt.tree/build/tnt.tree.css" type="text/css" />
<script src="http://d3js.org/d3.v3.min.js" charset="utf-8"></script>
<script src="http://tntvis.github.io/tnt.tree/build/tnt.tree.min.js" charset="utf-8"></script>

It is also possible to install the source code and build the library locally. This can be achieved done by using npm or github:

#Browser support

TnT works on HTML5, CSS3 and SVG-compliant browser, which generally means any "modern browser". The TnT library and themes are tested regularly against Chrome (Chromium) and major changes are regularly tested in recent versions of Firefox, Safari (Webkit) and Opera. It has been also tested in IE versions 9+. If you find any problem, please let me know.

The TnT library depends on the D3.js library. Check its browser's compatibility note for more information.

#Feedback

Please, send any feedback to emepyc@gmail.com. Bug reports and feature requests are also welcome in the issue tracker

Fork me on GitHub