jsPhyloSVG

by Paul Agapow
in science

tagged science, tools, phylogenetics, web-development

jsPhyloSVG (or JPS from this point) is a nifty Javascript library for displaying phylogenetic trees in your browser. It can:

  • accept trees in a number of formats, encoded in the page or on file or loaded via Ajax
  • allow these trees to be exported or saved as SVG
  • display trees in several formats
  • also display tree annotations & hyperlinks

On the down side, the documentation is middling and there are several hidden traps when using it. Here are some pointers from hard-won experience.

(Note added during editing: this is not to criticise the creators of JPS - at least they provide decent documentation and live examples. But the library is sufficiently powerful and large such that some points are missed or touched on only lightly, and it's easy for them to get lost. The below is what I consider to be a selection of the highlights and easiest things to misunderstand.)

Does it work in Internet Explorer?

Given the dubious support within IE for SVG, this is a good question that the documentation fails to address. It works in IE 8+, but it's unclear what the story is with 7. Some font and minor features may appear different (not broken) across platforms.

What formats does it accept?

Newick (the default), PhyloXml, NeXML, JSON (json-ized PhyloXML or NeXML). I assume Newick is what you're using. It's not very well-defined and there are lots of minor variants about which can cause issues (see below). But it's far more ubiquitous than the alternatives. However, several of the more advanced features of JPS can only be used with the XML formats.

The canonical and complete basic example

Trees can be embedded in a webpage like thus:

<html>
        <head>
                <script type="text/javascript" src="raphael-min.js"></script>
                <script type="text/javascript" src="jsphylosvg-min.js"></script>
        </head>
        <body>
        <div id="svgCanvas"></div>
        <script type="text/javascript">
        var dataObject = { newick: '(foo:0.00823353,(bar:0.0127245,                     baz:0.141467),quux:0.00374251);' };
        phylocanvas = new Smits.PhyloCanvas( dataObject, 'svgCanvas',
                500, 500);
        </script>
        </body>
</html>

Ideally you should pass the tree data and render it in an onLoad - to postpone rendering until after the page loading is complete - but the above will work. JPS uses Raphael to do the drawing, but it is included in the package.

Newick encoding

The Newick format presents a few problems. By experimentation, these appear to be the limitations within JPS:

  • In this case, the data object you must pass must have the property newick with the Newick string as its value
  • Taxa names cannot be quoted, e.g. 'foo'
  • Spaces within a taxa name are tolerated but not not outside a name. JPS appears to use non-alphanumerics to delimit taxa names and expects other taxanames / tree punctuation to follow immediately.
  • While spaces might be okay in a name, hyphens are not
  • Very small distances are okay
  • The tree specification must be finished with a semi-colon.

So this is okay:

(Whipped Cream:1,Chocolate Syrup:1,Cafe Mocha:3)

and this isn't:

('Whipped Cream':1, Chocolate-Syrup:1, Cafe Mocha:3)

If the tree does not meet these requirements, two things could happen:

  • a malformed tree is drawn (look for brackets and other "punctuation" embedded in tree names
  • the tree-parsing code (apparently) gets stuck in a loop and never returns, causing the page to apparently "hang". IN Chrome, even stopping the page and reloading would often fail to fix this behaviour. I had to eventually close the tab.

Also worth knowing is that branchlengths do not have to be provided on the tree. Absent ones are assumed to be 1.

Parameters

JPS spends most of its time on the PhyloXML format, neglecting or only implying the parameters for direct calls. Here's a few examples. You can draw a radial tree, like this:

phylocanvas = new Smits.PhyloCanvas (
        dataObject,   // a string in Newick or XML
        'svgCanvas',  // the div within which to render the tree
        1000, 1000,   // height & width of tree after rendering, in pixels
        'circular'    // draw a radial tree
);

There's a few other odd things too. For unclear reasons, the circular depiction of the tree will sometimes overflow its box, giving it a odd cropped look. 1000 by 1000 seems to work under most circumstances. Note - and this is completely unclear in the documentation - in the radial pictures, the branch lengths are drawn as dotted beyond their actual lengths so that they reach the outer edge of the circle.

"Interactive features" are restricted to the XML formats.

Style parameters can be altered from Javascript. The documentation refers to a render-styles.js but actually everything is in the main JPS file. These can be altered directly in your code (or passed in the XML):

Smits.PhyloCanvas.Render.Style.line.stroke = 'rgb(0,0,255)';
// Color lines blue
Smits.PhyloCanvas.Render.Style.text["font-size"] = 16;
// Increase font size to 16pt

Save tree as SVG

There is an example in the documentation that shows how to do this. However, it's moderately complex and requires one of the major JS toolkits (JQuery, YUI) to do the necessary popups and handling.