API Reference

TnT

TnT is a javascript library built on top of TnT Tree and TnT Board to visualise trees and track-based annotations. There are several components that need to be set up in this visualisation: the tree, the board where the annotation is displayed and a track function that creates tracks for each leaf in the tree. All the methods available in TnT Tree and TnT Board are available plus some specific to TnT to synchronise the tree with the board.

// The tree
var tree = tnt.tree()
    .data(tnt.tree.parse_newick("((human, chimp),mouse)"))
    .width(500)

// The board
var board = tnt.board()
    .width(400)
    .from(0)
    .to(1000)
    .max(1000);

// The function to create tracks for each tree leaf
var track = function (leaf) {
    var data = leaf.data();

    return tnt.board.track()
        .color("white")
        .data(tnt.board.track.data.sync()
            .retriever (function () {
                var elems = [];
                // populate elems and then return them
                return elems;
            })
        )
        .display(tnt.board.track.feature.block()
            .color("steelblue")
            .index(function (d) {
                return d.start;
            })
        );
}


// The TnT Vis
var vis = tnt()
    .tree(tree)
    .board(board)
    .track(track);

vis(document.getElementById("mydiv"));

In the snippet above, a tree, a board and a function to create tracks based on tree leaves are defined, configured and attached to a new TnT visualisation. This visualisation is then called using a div element as its container.

#TnT

# .tnt ()

Creates a new TnT Visualisation. It can be configured via several methods described below.

var vis = tnt();

# tnt.tree (<tnt.tree>)

Sets the tree (ie the tnt.tree) to the TnT visualisation. If called without arguments, retrieves the current tree.

var tree = tnt.tree()
    .data (tnt.tree.parse_newick (newick));
    // other methods to configure the tree

var vis = tnt()
    .tree (tree);

# tnt.board (<tnt.board>)

Sets the annotation board (ie the tnt.board) to the TnT visualisation. If called without arguments, retrieves the current board.

var board = tnt.board()
    .from (0)
    .to (1000)
    .width (400)
    .max (1000);

var ta = tnt()
    .board (board);

# tnt.track (<callback>)

Sets a callback to create new tracks based on tree leaves. The callback receives a tnt.tree.node and must return a tnt.track. This callback is used by tnt to create the tracks in the board. It is called when the visualisation is started and every time it is updated (using the tnt.update method). The tracks are re-created dynamically if a new callback is set after the visualisation has started. If called without arguments returns the current callback.

var track = function (leaf) {
    var sp = leaf.name;
    return tnt.track()
        .color ('#E8E8E8')
        .data (tnt.track.data.sync()
            .retriever (function () {
                return data[source][sp] || [];
            })
        )

        .display (...);
};

var vis = tnt()
    .tree (...)
    .board (...)
    .track (track);

vis (div);

# tnt.update ()

Dynamically updates the tree and the board of the visualisation. If the leaves are re-ordered, collapsed, etc, their associated tracks are updated accordingly

var vis = tnt()
    .tree (tree)
    .board (board)
    .track (track);

vis(div);

// Toggle one node and update the visualisation
tree.root().find_node_by_name ('Mammals').toggle();
vis.update();

# tnt.top (<tnt.board.track>)

Sets the top track to be displayed in the board. This track will not be part of the tracks being linked to the tree leaves. Typically this can be an axis, but can be configured as required.

var axis_top = tnt.board.track()
        .height(0)
        .color("white")
        .display(tnt.board.track.feature.axis()
            .orientation("top")
        );
tnt()
    .top(axis_top)

# tnt.bottom (<tnt.board.track>)

Sets the bottom track to be displayed in the board. This track will not be part of the tracks being linked to the tree leaves. Typically this can be an axis, but can be configured as required.

var axis_bottom = tnt.board.track()
        .height(0)
        .color("white")
        .display(tnt.board.track.feature.axis()
            .orientation("bottom")
        );
tnt()
    .top(axis_bottom)

# tnt.key (<string | callback>)

Specifies the key to be used when linking tree nodes and tracks. By default, the nodes and the tracks are linked by internal IDs transparent to the user. If some kind of object constancy (node constancy) is required, it is possible to define a different way to link leaves and tracks. This new key can be defined either using a field name in the data or a callback that would be called on each leaf when creating or updating tracks. This callback is called with the leaf node (ie the tnt.tree.node) as its argument.

var newick1 = '((human, chimp), (mouse, rat));';
var newick2 = '(((human, chimp), mouse), zebrafish)';

var tree1 = tnt.tree.parse_newick (newick1);
var tree2 = tnt.tree.parse_newick (newick2);

var vis = tnt()
    .tree (tree1);
    .key ('name'); // or .key (function (node) { return node.node_name() });

// at some later point... a new tree is set in the tree annot. Because this is a different tree, if no key is defined for the tree annotation, no track constancy or node constancy would not be performed, but because we are using the 'name' field of the node to link leaves and tracks, when using the second tree, the common leaves (ie 'human, 'chimp' and 'mouse') and their associated annotation would be maintained
vis
    .tree (tree2)
    .update();