API Reference



Class Name Description
Tree Describes the whole tree object, as well as the functions related to viewing the tree. Should possibly be split into 2 objects, the Tree and the Viewer
Branch Describes an individual branch in the tree
Navigator Descibes the optional overview that shows the position of the current view relative to the whole tree. requires work




Properties Type Description
backColour bool/function (default : false) Possible values:
  • false : the branches are all coloured according to Tree.branchColour
  • true : leaves are coloured according to their .colour property. If all of an Internal branches children are of the same colour the branch takes that colour, otherwise it uses Tree.branchColour
  • {string:rgba} function(branch) : the branch colour is determined by the colour returned by the function. Ideally the returned colour should be an RGBA value
baseNodeSize integer The radius of a leaf tip if no other size is specified
branchColour rgba value The normal colour of the branches
branchScalar double A multiplier for the branch length to produce the best possible definition between branch lengths (branchLength * branchScalar = drawnLength)
branches object An object containing each branch keyed by it's ID. Internal branches without IDs are given generated Ids prefixed with 'pcn', the root will typically be 'pcn0'
canvas HTMLCanvasContext The canvas used to draw the tree
canvasEl HTMLDivElement The element that contains PhyloCanvas. Should normally be a block element. (Slight misnoma for legacy reasons)
contextMenu PhyloCanvas.ContextMenu A reference to the context menu object that belongs to this instance
dragging boolean A variable for internal use the records whether the pre-render has run (named for legacy reasons)
nodeAlign boolean (default: false) To align all the nodes vertically
drawn boolean The font face to use for tree labels
drawn boolean A variable for internal use the records whether the pre-render has run (named for legacy reasons)
font string The font face to use for tree labels
highlightColour rgba value The colour of the highlighted branches
hightlightWitdh integer (default : 5) How much bigger do highlighted nodes/branches get
hoverLabel boolean If the labels are turned off, and this is true, show the node label when hovering over the node tip.
internalNodesSelectable boolean true/false to make internal nodes selectable or not. If false then only leaves will be selectable
lastId integer The last id returned by the id generator
leaves array - PhyloCanvas.Branch[ ] An array of every node without children, the tips of the tree
lineWitdh double (default:1.0) The witdh of the lines that make up the branches, as well as the outline of the nodes
maxBranchLength double, read only The max branchlength from the root of the tree to the furthest tip
offsetx/offsety integer The the position of the diagram origin (0,0) relative to the centre of the viewer
origBL object The original branch lengths, populated when a subtree is drawn
origP object The original parent of the new root, populated when a subtree is drawn
pickedUp boolean Is the left mouse button being held down over the tree
rightClickZoom boolean (default : true) Enable zooming the tree by dragging with the right mouse button
selectedColour rgba value The colour the branch and node change to when selected
selectedNodeSizeIncrease integer (default : 0) How much bigger do selected nodes get
showBootstrap boolean (default:false) Whether or not to show all the bootstrap confidence values
showLabels boolean (default: true) Whether or not to draw all the leaf labels
textSize integer The size of the branch labels (in px)
treeType string (default : radial) which branchRenderer to use, supplied renderers are: radial, rectangular, circular, diagonal and hierarchy
root Branch A reference to the root of the tree
unselectOnClickAway boolean (default : true) Deselect when the user clicks on somewhere on the canvas that isn't the tree
selectedNodes array - PhyloCanvas.Branch[ ] An array of the selected branches
zoom double The current Zoom level
shotMetadata boolean (default: false) Show / hide metadata.
Metadata should be stored in the data object of each leaf node in the below format
  data: {
    columnheading1: value (0/1),
    columnheading2: value (0/1),
    columnheading3: value (0/1),
    columnheadingN: value (0/1)
Once rendered, all true values (1) will be shown in a rectangular block representing presence or absence in a tabular format;
color1 rgb/hex/color-names Color to be used for the overlayed rectangular block representing presence or absence

Tree - Functions

Function Parameters Description
  • url
  • method
  • params
  • callback
  • callbackPars
  • scope
  • errorCallback
Make an AJAX call and pass the data returned to the callback. Used in the load method
  • event_name
  • listener
attach a listener to an event from the tree
  • event_name
  • listener
attach a listener to an event from the tree
adjustForPixelRatio compensate for Retina display/browser zoom
  • collection
Functions that enable the drawing of different tree structures. Default branchRenderers are radial, rectangular, circular, diagonal, hierarchy
buildLeaves Reconstruct the leaves array in the correct order after a rotation
  • event
Handler for mouse clicked event on the canvas
  • event
Handler for mouse double click event on the canvas
  • event
Handler for mouse drag event on the canvas
  • event
Handler for mouse drop event on the canvas
  • event
Handler for mouse pickup event on the canvas
  • event
Handler for mouse scroll event on the canvas
displayLabels Show the lables on the tree
  • forceRedraw
Draw the tree with the settings provided, forceRedraw causes the prerenderer to redraw. forceRedraw = true/false
exportNwk Return the newick string of the currently displayed tree
  • pattern
Find a branch accodring to the pattern provided.
Case insensitive match against the leaf ID
fitInPanel fit the tree within the current canvas panel
genId Generate a node Id prefixed with 'pcn'
getBounds get the overall size of the tree
getPngUrl Get the dataURL for the current view
hideLabels Hide the lables on the tree
  • filename
  • tree_name
  • format

Parse a newick or nexus format string and draw the tree

filename (String)
The name of the file you wish to open via AJAX or the Newick or Nexus String
tree_name (String)
If using nexus format, the name of the tree to draw. But default Phylocanvas picks the first tree
format (nexus|newick)
Override the parsing algorithm for the string provided
loadCompleted Fire the event that signals the load is completed
  • message
Fire the event that signals the load has failed
loadStarted Fire the event that signals the load has started
  • collection
Render the tip of a leaf. Extensible collection that includes
circle (default), square, triangle, star.

Rotation and offset of the canvas are set so that 0,0 is the tip of the branch.

nodeSelected(nids) Fire the event that signals nodes have been selected
  • nexus_string
  • name
Parse a nexus formatted string. If using Nexus the tree name should be specified, normally these methods are invoked from within the load function
  • Newick string
Parse a Nexus or nwk formatted string.
  • collection
Functions calculate the structure of the tree before drawing. Default pre-renderers are radial, rectangular, circular, diagonal, hierarchy.
  • node
  • leafIds
recursively get the IDs of the leaves in a sub-tree, putting the results in leafIds
  • node
Redraw a sub-tree from an internal node of a tree.
redrawOriginalTree redraw the tree from it's original root
resetTree Reset the tree ready for the pre-renderers to recalculate
resizeToContainer Fit the whole widget within it's parent div
  • branch
Reverse the order a branch's children are drawn in
  • node
Atd a node to the tree. Used by the parsers.
  • nodeIds
Select the nodes specified by node ids (array or comma seperated list). N.B. all leaves must be adjacent in the tree
  • font
Change the font for the node labels
  • nodeIds
  • colour
  • shape
  • size
  • waiting
Change the node colour and/or shape, optional arguments must be replaced by null or undefined if subsequent arguments are set. All the parameters are optional except nodeIds.
nodeIds: (Array/String)
Array / comma separated string.
Color of the node in rgb/hex/colornames format Eg: red, rgb(255,0,0), #adadad
  • x = star
  • s = square
  • o = circle
  • t = triangle
Size of the node
  • size
Set the base size of all the nodes
  • node
Set the root node of the tree
  • size
Set the size of the labels
  • type

Hide the lables on the tree

type (String)
The name of the type of tree to change to (rectangular, radial, circular, diagonal, hierarchy)
  • width
  • height
Set the size of the tree
  • zoom_level
Set the zoom level of the tree
toggleLabels Toggle the labels on and off
  • click_x
Take the X postion of the click from the browser event and turn it into a position relative to the tree
  • click_y
Take the Y postion of the click from the browser event and turn it into a position relative to the tree
  • old_type
  • new_type
Fire the event that signals the tree type has been changed


PhyloCanvas exposes a number of events that allow web pages to change according to activity within PhyoCanvas. The API also exposes a couple of helper methods to enable binding of events to the API.

Helper Methods

Methods Parameters Description
  • event name
  • handler
Add the specified handler to the specified event name
  • event name
  • handler
Add the specified handler to the specified event name


Events Parameters Description
loading Fires when the widget starts loading a file via AJAX
loaded Fires when a tree has completed loading
  • node
Fires if an error is encountered by the loading or parsing process
The id of the node chosen as the new root
  • node
Fires when the user draws a subtree
The id of the node chosen as the new root
  • oldType
  • newType
Fires when the tree type is changed
The name of the type of tree that was being displayed before the type was changed
The name of the type of tree that the view was changed to
  • nodes
Fires when the user selectes node(s)
An Array of the IDs of selected node



Properties Description
angle The angle (clockwise from horizontal) of the node branch
branchLength The relative length of the branch as defined in the nwk/nexus string
canvas A reference to the canvas on which the branch is drawn
centrex/centrey The position of the end of the node.
children The child branches of this branch
collapsed Has the branch been collapsed
colour The fill colour of the node tip
data a custom object that can be used in conjustion with a custom noderenderer
id The unique identifier for a node, particulary for identifying leaf nodes, this becomes the key to Tree.branches
interx/intery Used by layouts that align all the nodes at the same distance from the root, but needing to show branch lengths (e.g. circular layout);
label The label shown next to the node. Blank strings will be displayed, if the label is null (default) or undefined the ID is displayed instead
leaf True if the branch has no children and is therefore a leaf
minChildAngle The minimum child angle
maxChildAngle The maxim child angle
startx The x position of the start of the branch (the parent nodes centrex/centrey)
starty The y position of the start of the branch (the parent nodes centrex/centrey)
totalBranchLength The total distance from the root of the tree to the tip of the branch
tree A reference to the tree object that this branch belongs too

Branch - Functions

Function Parameters Description
  • node
Add a child branch to this branch
  • x
  • y
see if this branch is the one that has been clicked given the x and y coordinates (output from Tree.translateClickX/Y)
collapse Collapse this branch
drawLabel Draw the label for this branch
drawNode draw the coloured tip of this branch
expand Expand (uncollapse) the node
getColour Get the tip or branch colour of this node depeneding on whether its a leaf or an internal node
getChildColours return an array of the colours of this childs children
getChildCount get the total number of children under this node and all of it's children.
getChildIds Return the IDs of all the leaves under this branch (recursively)
getChildNo Get the position of this node in it's parents children array
getChildYTotal Return the total distance on the Y axis occupied by this nodes children
getLabel return the text that labels this node, if no label is set return the node id
getLabelSize Return the width of this node's label
getNodeSize Get the size of the tip of the node
getNWK Return the nwk format string of this node
getTextColour Get the colour of the label
  • nwk_string
  • idx
Recursive parsing function for a Newick formatted tree file
  • nwk_string
  • idx
Parse a label from a Newick string
parseNodeLength Parse the node length from a nwk string
redrawTreeFromBranch Draw a subtree from this branch
reset set all the branches positional properties back to 0 ready for the next branch layout
rotate Reverse the order of the nodes immediate children. The reverse function is available in the right-click menu
saveChildren save this nodes children to the tree
  • true/false
Sets whether or not this branch is highlighted
  • selected
  • applyToChildren
Set whether the node is selected (true or false) and whether this should be applied to all it's children.
setTotalBranchLength calculate the total branch length property for this node
toggleCollapse Toggle this node between collapsed and expanded


The history panel of sub-trees


Properties Description
tree reference to the tree object
div the div containing the history

History - Functions

Function Parameters Description
reset Clear all the snapshots and then add the root snapshot
collapse Collapse the histroy panel into the left of the PhyloCanvas div
expand Show the History
isCollapsed return true if the history is collapsed and false if it isn't
toggle If the history is collapsed exapand it and vice-versa
  • parentDiv
Crete the div that will contain the history
resizeTree Adjust the size of the tree to compensate for the History being collapsed or expanded
  • id
Add a snapshot of the current tree view that will redraw the tree from the node with the ID id.
clear Remove all the snapshots
  • event
Click handler for the snapshots that removes the subsequent history entries.



Properties Description
elements Menu choices, an array of dictionaries with properties
The label of the menu item
The function in the Tree object that the menu item invokes. If a node has been clicked on it is padded to the handler
Does this function apply to an internal node
Does this function apply to a leaf

Configuring a context menu at the time of Tree initialization

phylocanvas = new PhyloCanvas.Tree('phylocanvas', {
  // other options
  contextMenu : [{
    text: 'Normal Menu',
    handler: 'triggerNormal',
    internal: false,
    leaf: false
  }, {
    text: 'Internal Menu',
    handler: 'triggerInternal',
    internal: true,
    leaf: false
  }, {
    text: 'Save as PNG',
    handler: 'exportCurrentTreeView',
    internal: false,
    leaf: false


ContextMenu - Functions

Properties Parameters Description
close Close the context menu
mouseover Hover function
mouseout Hover functions
  • x
  • y
Open the menu at position x, y