NCBI Tree Viewer Embedding API

The NCBI Tree Viewer (TV) is a tool for viewing phylogenetic tree data. It can be embedded in a wide variety of web pages and with a large number of options. This document serves as a starting point to understand how to embed the Tree Viewer in any context. For purposes of standardization in this document, all links presented have the common root http://www.ncbi.nlm.nih.gov.

Additional documentation can be found at: http://www.ncbi.nlm.nih.gov/tools/treeviewer/

Including Tree Viewer into a web page

The Tree Viewer is implemented using the ExtJS JavaScript library. Please do the following to include the tree viewer as a component on any page:

Include the main TreeViewer JavaScript file. When script is loaded it loads Ext.js dynamically.
- ```
<script type="text/javascript" src="http://www.ncbi.nlm.nih.gov/projects/treeview/js/treeviewer.js"></script>
```
- Tree Viewer will search for all <div> tags with class='TreeViewerApp' and one <a> tag with an href attribute containing viewer parameters, and create TV instances automatically. An example is:
```
<div id='some-id' class='TreeViewerApp'>
<a href='?embedded=true&btc_id=…'>,/a>
</div>
```
Do not use this method if the Tree Viewer div is initially hidden - it breaks all the logic as Tree Viewer needs to have real coordinates for proper rendering.
If you do not have Tree View parameters at the time of initializing your application (so you cannot put them into div of TreeViewerApp class in html file) please do the following:
- Include Tree Viewer JavaScript file:
```
<script type="text/javascript" src="http://www.ncbi.nlm.nih.gov/projects/treeview/js/treeviewer.js"></script>
```
- Create a div of TreeViewerApp class with no btc id and no url in parameters:
```
<div id='some-id' class='TreeViewerApp'>
<a href='?embedded=true'></a>
</div>
```
- Wait until TreeViewer is loaded:
  
  if (typeof TreeView === 'undefined') should be false
- Wait until your instance of tree is ready:
  
  if (TreeView.findAppByIndex(0) === null) should be false
- Access your tree and set parameters using reloadTree function:
  
  var tviewer = TreeView.findAppByIndex(0);
  if (tviewer) tviewer.reloadTree(par);

Sizing and Zooming

Tree viewer lets user zoom in and zoom out using zooming controls on toolbar and mouse wheel to have better visual representation of whole picture or details. TV calculates and controls maximum and minimum size for tree provided based on nodes amount, tree layout and geometry, labels sizes and spacing, and size of div, which contains Tree Viewer.

Embedder has control over first zoom level appearance of a tree by passing corresponding parameter, which represents zoom level. 0 will be minimum zoom, 100 will be maximum zoom. 50 percent will be optimal zoom (minimum level of zoom t which all nodes labels are readable).

Tree Viewer parameters

Parameters may be passed to Tree Viewer by putting them in the included <a href=''> _cke_saved_href=''> link tag within the Tree Viewer <div> tag.

Base parameters:

embedded={false, true} – default is false. This is a required parameter for an embedded version of Tree Viewer.
btc_id – mandatory. One of the following:
- NetCache ID of a serialized BioTreeContainer ASN.1 structure from which the tree image will be generated;
- File with a serialized BioTreeContainer ASN.1 structure; for security only files under a directory defined in the .ini file will be read;
- URL (HTTP/FTP) of a serialized BioTreeContainer ASN.1 structure from which the tree image will be generated.
url - ftp or http based file containing tree, which will be uploaded and shown in TreeViewer. Parameter url uploads the target file once.
urlreload - parameter url_reload always tries to re-upload the file to check the content, which can introduce a processing delay. If you use this parameter you don't have to create a file name versioning but this mode will be slower as it needs to download the file every time
attriburl - (optional) URL that should return phylogenetic-tree-compatible attributes file. Returned file is used to update node features.
attribupdate - (optional) If true, the updated tree is saved. It only works if the tree was read from NetStorage.
featnames – list of feature names to display in node tooltip. Default is ‘*’. List of names should be comma-separated.
toolbar = <abpztsohmcurl> Specifies which options are present on the toolbar. This parameter is optional and if omitted, all options are shown. If any options are specified, all other options must be opted in.
- a - Standalone button
- b - History button (not implemented yet)
- p - Panning buttons
- z - Zoom slider & buttons
- t - Tools menu
- s - Search field
- o - Overview button
- h - Help button
- m - Selection mode
- c - Clear selection
- u - Upload user data
- r - Refresh tree
- l - Labels edit dialog
statusbar = <npsm> Specifies which options are present on the statusbar. This parameter is optional and if omitted, all options are shown. If any options are specified, all other options must be opted in.
- n – Information about nodes amount and selected nodes amount
- p – Viewport position
- s – Image size
- m – Scale. Overrides scaleposition parameter
nostatusbar - if true, no statusbar will be displayed. Default value is false.
renderer - layout of the rendered tree, one of: rect, slanted, radial, or circular. Default value is circular
notoolbar - if true, no toolbar will be displayed. Default value is false
panX - number of pixels to move horizontally when user clicks on corresponding pan button. Default value is 50.
panY - number of pixels to move vertically when user clicks on corresponding pan button. Default value is 50.
scaleposition - position of scale in TreeViewer. Values: bottomleft, bottomright, topleft, topright. Defaulyt bottomleft.
rotatedlabels - if true and renderer=circular, render labels at an angle. Default value is false.
appname=<string> - Defines the name of the client calling the application. This is an optional parameter used in storing a user’s configuration settings; we recommend that all developers supply an application name. The name chosen should be unique; this name will appear in a cookie set in the user’s browser to indicate storage of configuration information. We strongly recommend that callers avoid using generic phrases like “tree” or “viewer”, and prepend a namespace (i.e., “NcbiPortalTree” or “XYZViewer”).
pctmaxzoom - number between 0 and 100 that represents zoom level. 9 will be minimum zoom, 100 will be maximum zoom. 50 percent will be optimal zoom (minimal level of zoom zt which all labels are readable). Default 0.
nodetooltips - Specifies if nodes will have tooltips, default - true.
labelformat - format string for generating node label from node features, default $(label).
maxlabellen - Truncate all labels with length greater than maxlabellen, default - 1 (no max).
centerpointX - if present, X coordinate of the center of displayed part of tree.
centerpointY - if present, Y coordinate of the center of displayed part of tree.
vertzoom - (true,false) - if true, zoom is in vertical direction only
zoom_on_wheel - If true, user can zoom Tree using mouse wheel. Default false and we strongly recommend to keep it this way, when embedding.
showpercentage - if True, current zoom level will be displayed in tooltip for zooming slider. Default true.
solidleaves - If true, all leaf nodes will be drawn in a uniform solid color, otherwise leaves will have highlights like other nodes. Default false.
multipleselectionmode -if true selection mode for nodes will be set to multiple. Default – false (single selection mode).
rootnoteid - if set, re-compute the tree with this node as the root and show the resulting tree
selectednodeIDs - comma-separated list of ids of the nodes to be shown as selected
collapsednodeIDs - IDs of nodes to collapse. A collapsed node becomes a leaf node, hiding all child nodes underneath.
subtreenodeID - only the subtree starting from this node will be shown
configpreset - Preset setup of configuration. Values – static. It will make TV appear like a static picture with no toolbar, node tooltips, no zooming and no scrolling.
nodesize - size of the node circle. Default value is 3.
linewidth - width of the tree branch line. Default value is 1.
select_on_click - shows if selection action should be performed when user clicks on node. Default value is true.
fontace - font name to be used in labels. Default value is Helvetica.
fontsize - size of font to be used in labels. Default value is 10.
labelspacing - scale dynamic viewport to adjust label spacing, 1.0=>minimum, 2.0=>doublespaced. Default – 2.0
horizspacing - scale horizontal spacing between branches as a factor of node size. Default – 7.0
clickablelabels - size of font to be used in labels. Default value is 10.
nodeaction = <bsrc> - Specifies which options are present on the toolbar. This parameter is optional and if omitted, all options are shown. If any options are specified, all other options must be opted in.
- b - Show subtree
- s - Select
- r - Reroute to node
- c - Toggle collapse/expand
setmidpointroot={false, true} - Default value: false. Optional. If true, tree is re-rooted using the midpoint algorithm.
collapsetoviewport={false, true} - Default value: false. If true it collapses enough nodes (by distance) to get the tree to fit (with labels visible) in the client viewport. It requires that the client viewport be provided and works with dynamic viewport. If the tree has a $PRIORITY field, it will automatically use that to avoid collapsing any nodes with $PRIORITY >= 1000.
leafnodesize=<num> - parameter supporting size of terminal, leaf nodes, num can be any floating point number including 0 for no leaf node

API functions

Getting application

TreeView.findAppByIndex

TreeView.findAppByDivId

Result: Returns instance of TreeViewApp.

Application functions

Events

Node Object Format Updates

nodeid -> id
depth -> d
parented -> pid
color -> clr
label -> l
seq_id -> seq_id // no change
seq_title -> seq_title // no change
accession_number -> acc_nbr
is-collapsed -> is_collapsed // no change
is_leaf -> il
is_selected -> is_sel
is_parent_selected -> is_psel
features -> feat
// And in features:
feat_name -> n
feat_value -> v
bounds -> bds
// and in bounds:
width -> w
height-> h
labelx -> lx
labely -> ly
label_angle -> la
tilex -> tx
tiley -> ty

Examples

{
  "id": 7,
  "d": 4,
  "pid": 6,
  "l": "YP_383193.1",
  "seq_id": "YP_383193.1",
  "seq_title": "bifunctional methionine sulfoxide reductase B/A protein [Geobacter metallireducens GS-15]",
  "il": true,
  "is_sel": true,
  "feats": [
    { "n": "label", "v": "YP_383193.1" },
    { "n": "dist", "v": "0.249507" },
    { "n": "seq-id", "v": "YP_383193.1" },
    { "n": "organism", "v": "Geobacter metallireducens GS-15" },
    { "n": "seq-title", "v": "bifunctional methionine sulfoxide reductase B/A protein [Geobacter metallireducens GS-15]" }
],
  "bds": { "x": 244, "y": 56, "w": 6, "h": 6, "lx": 249, "ly": 52, "lw": 56, "lh": 8, "la": 0, "tx": 0, "ty": 0 }
},

Loading Custom Trees

It is possible to display your own tree file in Tree Viewer. This file should be in asn (text or binary format) or in Newick format. This file should be stored at an ftp or http location. If you use “url” parameter for Tree Viewer (instead of btc_id parameter) and pass ftp or http URL as a value to a file containing tree - it will be uploaded and shown in Tree Viewer.

getVisibleNodes - returns list of nodes currently visible on a screen
showNode(node_id) - highlights node for several seconds
getSelectedNodes - returns a list of selected node ids
getSelectedNodesObjects - returns a array of selected node objects
selectNode(node_id) - toggles selection of node with given node ID
selectNodeByFeature (feature_name,feature_value,callback,no_signal,scroll_to_node) - toggles selection of nodes which have specified value for provided feature name (callback - function which will return you result in parameter in case something was selected, and no parameter if selection was not changed; if no_signal is not set to false appropriate API events will be fired in corresponding cases - see Events section below)
selectNodesByFeature (feature_name,feature_values,callback,no_signal,zoom_to_selection) -
toggleExpandNode (node_id) - Expands or collapses node
reloadTree (params) - Reloads tree with new set of parameters
getChildrenNodes (node_id) - Get list of all node which are children for node with provided node ID
customnodeactions - List of custom action for a node shown on tooltips. Empty by default. See sample usage below:
```
var tviewer = TreeView.findAppByIndex( 0 );
     if(tviewer)
     {
          tviewer.customnodeactions = [
               {
                    name : "Custom Action 1",
                    action : customAction
               },
               {
                    name : "Custom Action 2",
                    action : customAction2,
                    condition: "branch"
               }
             ]
     };
```
- 'node_label_mouseover': function(nd) - mouse cursor entered node label area
- 'node_label_mouseout': function(nd) - Mouse cursor exited node label area
- 'node_label_click': function(nd) - User clicked on node label
- 'node_mouseover': function(nd) - Mouse cursor entered node area
- 'node_mouseout': function(nd) - Mouse cursor exited node area
- 'nodes_changed' - Any change in nodes on screen
- 'node_selection_changed' - Change in nodes selection
- 'selection_not_changed_API' - no change in nodes selection triggered by API
- 'node_selection_changed_API' - change in nodes selection triggered by API

Tree Viewer documentation home
Tree Viewer application home
For Users
User Tutorials
For Developers
Related Resources
- Sequence Viewer
- Multiple Sequence Alignment Viewer

NCBI Tree Viewer