Fundamentals

This section describes basic commands for displaying trees, such as those found in the Introduction section.

Note that many methods follow the getter/setter pattern, commonly used in D3. That is, they can either be used to retrieve an underlying parameter by being invoked without arguments (get), or can be used to change an underlying parameter by being invoked with the proper arguments (set).

Supported formats

Phylotree supports the Newick format, as well the extension of this format that is used by HyPhy. This allows assigning a category to each branch by the use of curly braces directly after identifiers, e.g.:

((((Pig:0.147969,Cow:0.21343):0.085099,Horse:0.165787,Cat:0.264806):0.058611, ((RhMonkey{Foreground}:0.002015,Baboon{Foreground}:0.003108){Foreground}:0.022733 ,(Human{Foreground}:0.004349,Chimp{Foreground}:0.000799){Foreground}:0.011873):0.101856) :0.340802,Rat:0.050958,Mouse:0.09795)

Additionally, it supports two common XML formats in phylogenetics, namely the PhyloXML and NeXML formats.

Reading and writing trees

The following is the main method for instantiating a phylotree. It is attached to the d3.layout namespace.

d3.layout.phylotree([container])

Instantiate a phylotree.

Arguments:
  • container (d3-selection) – Specify a container, for things like menu and tooltip placement. Defaults to body (optional).
Returns:

function – phylotree - an instance of a Phylotree.

Phylotrees are themselves functions, with many methods attached and variables that have been closed over to provide an internal state. Newick, PhyloXML, and NeXML formats are supported.

phylotree.phylotree(nwk[, bootstrap_values])

An instance of a phylotree. Sets event listeners, parses tags, and creates links that represent branches.

Arguments:
  • nwk (Object) – A Newick string, PhyloXML string, or hierarchical JSON representation of a phylogenetic tree.
  • bootstrap_values (Object) – SDS: Not sure what this does.
Returns:

Phylotree – phylotree - itself, following the builder pattern.

d3.layout.phylotree.nexml_parser(xml_string)

A parser for NexML. This is a separate function, since NeXML objects can contain multiple trees. Results should be passed into a phylotree object, as shown in the examples.

Arguments:
  • nexml (Object) – A NeXML string.
Returns:

Object – trees - An array of trees contained in the NeXML object.

Internally, Phylotree.js uses the D3 hierarchy layout. The following function parses Newick strings into a hierarchical JSON format. Certain ad-hoc extensions, such as those used by HyPhy or Beast, are (partially) supported.

d3.layout.newick_parser(nwk_str[, bootstrap_values])

Parses a Newick string into an equivalent JSON representation that is suitable for consumption by d3.layout.hierarchy.

Optionally accepts bootstrap values. Currently supports Newick strings with or without branch lengths, as well as tagged trees such as

(a,(b{TAG},(c{TAG},d{ANOTHERTAG})))
Arguments:
  • nwk_str (String) – A string representing a phylogenetic tree in Newick format.
  • bootstrap_values (Object) – SDS: Not clear what this does (optional).
Returns:

Object – An object with keys json and error.

Trees may be serialized to Newick strings, possibly after having been annotated, for downstream use in an application.

phylotree.get_newick([annotator])

Return Newick string representation of a phylotree.

Arguments:
  • annotator (function) – Function to apply to each node, determining what label is written (optional).
Returns:

String – newick - Phylogenetic tree serialized as a Newick string.

phylotree.get_parsed_tags()

Return tags that were read when parsing the original Newick string.

Returns:An array of strings, comprising each tag that was read.

Drawing trees

In order to render a phylotree, an SVG element needs to present in the body of the document. One can specify which svg to render within with the following function.

phylotree.svg(svg_element)

Getter/setter for the SVG element for the Phylotree to be rendered in.

Arguments:
  • svg_element (d3-selection) – (Optional) SVG element to render within, selected by D3.
Returns:

The selected SVG element if getting, or the current phylotree if setting.`

Once a tree has been parsed and an SVG element chosen, the following function is called to render the tree.

phylotree.layout([transitions])

Lay out the tree within the SVG.

Arguments:
  • transitions (Boolean) – Specify whether or not transitions should occur.
Returns:

The current phylotree.

Formatting trees

The following methods are getters/setters for various formatting options.

phylotree.size([attr])

Get or set the size of tree in pixels.

Arguments:
  • attr (Array) – (optional) An array of the form [height, width].
Returns:

Phylotree – The current size array if getting, or the current phylotree if setting.

phylotree.spacing_x([attr, skip_render])

Get or set spacing in the x-direction.

Arguments:
  • attr (Number) – (Optional), the new spacing value if setting.
  • skip_render (Boolean) – (Optional), whether or not a refresh should be performed.
Returns:

The current spacing_x value if getting, or the current phylotree if setting.

phylotree.spacing_y([attr, skip_render])

Get or set spacing in the y-direction.

Arguments:
  • attr (Number) – (Optional), the new spacing value if setting.
  • skip_render (Boolean) – (Optional), whether or not a refresh should be performed.
Returns:

The current spacing_y value if getting, or the current phylotree if setting.

phylotree.font_size([attr])

Get or set font size.

Arguments:
  • attr (function) – Empty if getting, or new font size if setting.
Returns:

The current font_size accessor if getting, or the current phylotree if setting.