API Reference

Genome

TnT Genome is built on top of TnT Board and exposes the same methods explained in TnT Board's API. TnT Genome also offers a few elements explained below. The most important are: three new displays for genes, transcripts and genomic sequences, a modified location display that includes the species and the chromosome being displayed in the board, a layout that avoids overlaps in genes and transcripts and integration with the Ensembl REST API to fetch genomic data through TnT Rest.

  // Genome is a board. Location and axis tracks are included by default
  var genome = tnt.board.genome().species("human").gene("brca2").width(950);

  var gene_track = tnt.board.track()
      .height(200)
      .color("white")
      .display(tnt.board.track.feature.genome.gene()
          .color("#550055")
      )
      .data(tnt.board.track.data.genome.gene());

  var sequence_track = tnt.board.track()
          .height(30)
          .background_color("white")
          .display(tnt.board.track.feature.genome.sequence())
          .data(tnt.board.track.data.genome.sequence()
              .limit(150)
          );
  genome
      .zoom_in(100)
      .add_track(sequence_track)
      .add_track(gene_track);

  genome(document.getElementById("mydiv"));
  genome.start();
  

In the example above a new genome board is createdand configured using the two new methods species and gene. Then two tracks are created using the new data endpoints and displays: the first one is a gene track and the second one a sequence track. Although no location or axis tracks are set in the board explicitely they are included by default in the genome board. min and max are set automatically to 0 and the chromosome length respectively by default. The rest of the elements are the same explained before for TnT Board.

#Genome Visualisation

The genome board is a special type of tnt.board that inherits all its elements. A new genome board can be created using tnt.board.genome. An example of use looks like:

// Giving species and gene name
var genome = tnt.board.genome()
    .species("human")
    .gene("brca2")
    .width(950);

// Giving an ensembl ID (no species needed)
var genome = tnt.board.genome()
    .gene("ENSG00000012048");

// Giving a genomic region
var genome = tnt.board.genome()
    .species("human")
    .chr(13)
    .from(30665877)
    .to(31380905);

      

# tnt.board.genome ()

Creates a new genome board that can be configured using the methods explained below. The returned genome is a function itself that can be called passing a DOM element as its argument. This DOM element is used as a container for the visualization.

var genome = tnt.board.genome();
genome (document.getElementById ('my_div'));

         

# genome.species (<string>)

Sets the species for the genome board. Only species included in Ensembl are supported. Both scientific names (ie, "homo_sapiens") and common names ("human") are allowed. When called without arguments returns the current species. By default the species is "human".

var genome = tnt.board.genome()
    .species("mus_musculus");

         

# genome.chr (<integer>)

Sets the chromosome for the visualisation. When called without arguments returns the current chromosome.

var genome = tnt.board.genome()
    .chr(13);

         

# genome.gene (<string>)

Sets the gene to show in the genome visualisation. This gene can be a gene name (for example, "BRCA2") or an ensembl ID ("ENSG00000139618"). If the former is provided it is also needed to specify the species since the gene name may not be unique among species. When called without arguments returns the current gene.

var genome = tnt.board.genome()
    .species("human")
    .gene("BRCA2");

         

# genome.min_coord (<Promise>)

Sets the minimum allowed genome coordinate in the visualisation. It accepts a Promise. It defaults to a promise resolving to 0

// Example using es6-promise library. Any other Promise library can be used
var genome = tnt.board.genome()
     .species("human")
     .gene("BRCA2")
     .min(new Promise (function (resolve) {
         resolve (0);
     }))

         

# genome.max_coord (<Promise>)

Sets the maximum allowed genome coordinate in the visualisation. It accepts a Promise. It defaults to a promise resolving to the max coordinate for the chromosome.

// Example using es6-promise library. Any other Promise library can be used
var genome = tnt.board.genome()
     .species("human")
     .gene("BRCA2")
     .max(new Promise (function (resolve) {
           resolve (714314324);
     }))

         

# genome.expand (<integer>)

Sets extra space in the visualisation when the genome is centered to a given gene. Instead of starting the visualisation exactly on the specified gene some extra five and 3 prime space is given. The argument to the function is the the percentage of the extent and it is added to both ends (5' and 3') of the genome board.

var genome = tnt.board.genome()
    .species("human")
    .gene("BRCA2")
    .expand(25); // extends the board to cover 25% more genome space to both sides

         

#Display

TnT Genome provides 3 new data displays for genes, transcripts and genomic sequences. They understand the data elements fetched by their corresponding data retrievers explained below.

var gene_track = tnt.board.track()
    .height(200)
    .color("white")
    .data(tnt.board.track.data.genome.gene())
    .display(tnt.board.track.feature.genome.gene()
        .color("#550055")
    );


var sequence_track = tnt.board.track()
    .height(30)
    .color("white")
    .data(tnt.board.track.data.genome.sequence()
        .limit(150)
    );
    .display(tnt.board.track.feature.genome.sequence());

      

# tnt.board.track.feature.genome.gene ()

Creates a new gene display. This has the same methods and properties as any other TnT Board display. It understands the elements retrieved by the gene data retriever.

var gene_display = tnt.board.track.feature.genome.gene();

         

# tnt.board.track.feature.genome.transcript ()

Creates a new transcript display. This has the same methods and properties as any other TnT Board display. It understands the elements retrieved by the transcript data retriever.

var transcript_display = tnt.board.track.feature.genome.transcript();

         

# tnt.board.track.feature.genome.sequence ()

Creates a new sequence display. This has the same methods and properties as any other TnT Board display. It understands the elements retrieved by the sequence data retriever.

var sequence_display = tnt.board.track.feature.genome.sequence();

         

#Data

TnT Genome provides an interface to the Ensembl REST API to fetch genomic data. This interface uses tnt.board.track.data.async under the hood, which means that uses ES2015 promises that can be chained with user-defined functions.

var gene_track = tnt.board.track()
    .height(200)
    .color("white")
    .display(tnt.board.track.feature.genome.gene()
        .color("#550055")
    )
    .data(tnt.board.track.data.genome.gene());

var sequence_track = tnt.board.track()
        .height(30)
        .background_color("white")
        .display(tnt.board.track.feature.genome.sequence())
        .data(tnt.board.track.data.genome.sequence()
            .limit(150)
        );

      

# tnt.board.track.data.genome.gene ()

Creates a new gene retriever using the Ensembl REST API. Returns a promise that can be chained with other user-defined functions.

var gene_data = tnt.board.track.data.genome.gene();

         

# tnt.board.track.data.genome.transcript ()

Creates a new transcript retriever using the Ensembl REST API. Returns a promise that can be chained with other user-defined functions.

var transcript_data = tnt.board.track.data.genome.transcript();

         

# tnt.board.track.data.sequence.sequence ()

Creates a new sequence retriever using the Ensembl REST API. Returns a promise that can be chained with other user-defined functions.

var sequence_data = tnt.board.track.genome.sequence();

         

# sequence.limit (<integer>)

Sets a limit for returning the genomic sequence. If the length of the sequence to retrieve is greater than the limit, nothing is returned or displayed. By default, this limit is set to 150. If called without arguments returns the current limit

var sequence_data = tnt.board.track.genome.sequence()
    .limit (200);

         

#Layout

The layout analyses all the genes, transcripts and labels in a track and distributes them vertically to avoid overlaps. It is set as a property of the board's display. It is run after the data is retrieved and before the elements are displayed. It also supports several configuration methods explained below. The layout normally doesn't need to be set up by the library user.

# display.layout (<tnt.board.track.layout>)

Sets a layout for the elements of a track. It accepts a tnt.board.track.layout as its argument. When called without arguments returns the current layout. In TnT Genome the layout is set to tnt.board.track.layout.genome, that avoids overlaps between elements to display (and their labels). This method is specially useful to configure this default layout.

// expand or contract the height of the gene track as needed
var curr_layout = gene_track.display().layout();
curr_layout
    .fixed_slot_type("expanded")
    .keep_slots(false)
    .on_layout_run (function (types, current) {
        var needed_height = types.expanded.needed_slots * types.expanded.slot_height;
        if (needed_height !== current_height) {
            current_height = needed_height;
            gene_track.height(needed_height);
            genome.tracks(genome.tracks());
        }
    });

         

# tnt.board.track.layout.genome ()

Default layout for genes and transcripts. It avoids overlaps between genes or transcript (including their labels). The layout distributes the elements (genes or transcripts) into slots. The elements are placed in the different slots available (based on the height of the track) avoiding overlaps using a _expanded_ display. When there are too many elements to ensure that the overlaps are avoided the layout notifies that and the display uses a _collapsed_ display in which the labels are not shown and the element's height is reduced.

# genome.fixed_slot_type (<string>)

Specifies if the layout should always keep the slot type. By default the layout shows genes expanded (see above) if they all fit in the current board and collapsed if they don't. Setting this option to "expanded" the genes will always be shown in the former form. Using "collapsed" as its argument uses always the latter.

gene_track.display().layout()
    .fixed_slot_type("expanded");

         

# genome.keep_slots (<boolean>)

Specifies if the elements should keep their assigned slot between updates. By default this is set to true which means that elements (genes or transcripts) that are in display between two updates will keep their vertical position to reduce the amount of transitions. Once they go out of sight, they are removed from the track. If this option is set to false the layout recomputes the positions of the elements (genes or transcripts) on every data update.

gene_track.display().layout()
    .keep_slots(false);

         

# genome.on_layout_run (<callback>)

Sets a callback to be run after the layout has finished positioning elements. That callback is called with the an object containing the two slot types described above and the name of the one currently used.

gene_track.display().layout()
    .on_layout_run (function (types, current) {
        var needed_height = types.expanded.needed_slots * types.expanded.slot_height;
        if (needed_height !== current_height) {
            current_height = needed_height;
            gene_track.height(needed_height);
            genome.tracks(genome.tracks());
        }
    });