TnT Board

Visualization of track-based annotation

#Introduction

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

TnT Board defines several elements to facilitate the creation of visualisations: a board that is a container for tracks, tracks that are independent units of data representation, data retrievers to get the data synchronously or asynchronously and visual features to display the available data.

Boards

In TnT Board, a board is an interactive container for tracks. Each panning or zoom event in the board triggers new data and visualisation updates in the attached tracks. New boards are created using the tnt.board method. Once it is created new tracks can be attached using the board.add_track method. Boards are configured via several methods that are fully explained in the API page.

var myBoard = tnt.board()
    .from(0)
    .to(1000)
    .min(0)
    .max(1000);
myBoard
    .add_track(track1)
    .add_track(track2);

myBoard(document.getElementyById('DOM_element_id'));
myBoard.start();

As shown in the example above, the board itself is a function that when executed initialises the visualisation using the provided DOM element as its DOM container. After initialistion, the board is started, which means that each track retrieves and displays its data it. It is important to understand these three states of the visualisation:

Defined: The board instance is defined at the code level, but the visualisation hasn't been inisialised and the container is still empty
Initialised: The container is populated with the board elements
Started: The tracks are created, their data retrieved and the features plotted

Tracks

In TnT Board, tracks are 1-dimensional independent units of data representation, which means that each track is independent from each other and defines its own way of data retrieval and representation. When it is defined, each new track selects how the data for the track is retrieved (either synchronously or asynchronously) and displayed. TnT offers predefined common displays (like rectangles, lines, areas, pins, etc) ready to use and new displays can also be created using the display interface. Composite displays are also allowed and a very powerful tool for displaying complex data. One of the main characteristics of TnT Board is the separation of concerns between data retrieval and data representation. Check the API documentation for a full list of methods available for tracks, data retrievals and displays

#Example

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

  var myBoard = tnt.board().from(0).to(500).left(0).right(500);

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

  var blockTrack = tnt.board.track()
      .height(30)
      .color("#FFCFDD")
      .data (tnt.board.track.data.sync()
          .retriever(function () {
              return [{
                  start : 200,
                  end : 350
              }];
          })
      )
      .display(tnt.board.track.feature.block()
          .color("blue")
          .index(function (d) {
              return d.start;
          })
      );

  // Attach the tracks to the board (order matters)
  myBoard
      .add_track(location_track)
      .add_track(block_track);

  // Initialise the board
  myBoard(document.getElementById("mydiv"));

  // Starts the visualisation
  myBoard.start();

The above example starts by defining a board that displays data from position 0 to 500, being the minimum and maximum coordinates 0 and 1000 respectively. The code also defines two tracks and each of them defines how the data is retrieved and displayed. Once defined, the tracks are attached to the board using the add_track method. The first one is a location track. The second track is 30 pixels high and displays one block from position 200 to 350 in the board. Once the board is configure the visualisation is ready to start.

#Installation

TnT Board can be linked directly from the github repo. It depends on d3js and this library needs to be linked before tnt.board

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

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

Using npm:
```
npm install tnt.board
        
```

Building from Git:

git clone https://github.com/emepyc/tnt.board
cd tnt.board
npm install
npm build-browser

#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 project's issue tracker