API Reference


Top

Classes

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

Top

PhyloCanvas.Tree

Configuration

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
Top

Tree - Functions

Function Parameters Description
AJAX
  • url
  • method
  • params
  • callback
  • callbackPars
  • scope
  • errorCallback
Make an AJAX call and pass the data returned to the callback. Used in the load method
addListener
  • event_name
  • listener
attach a listener to an event from the tree
on
  • event_name
  • listener
attach a listener to an event from the tree
adjustForPixelRatio compensate for Retina display/browser zoom
branchRenderers
  • 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
clicked
  • event
Handler for mouse clicked event on the canvas
dblclicked
  • event
Handler for mouse double click event on the canvas
drag
  • event
Handler for mouse drag event on the canvas
drop
  • event
Handler for mouse drop event on the canvas
pickup
  • event
Handler for mouse pickup event on the canvas
scroll
  • event
Handler for mouse scroll event on the canvas
displayLabels Show the lables on the tree
draw
  • 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
findBranch
  • 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
load
  • 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
loadError
  • message
Fire the event that signals the load has failed
loadStarted Fire the event that signals the load has started
nodeRenderers
  • 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
parseNexus
  • 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
parseNwk
  • Newick string
Parse a Nexus or nwk formatted string.
prerenderers
  • collection
Functions calculate the structure of the tree before drawing. Default pre-renderers are radial, rectangular, circular, diagonal, hierarchy.
redrawFromBranch
  • node
  • leafIds
recursively get the IDs of the leaves in a sub-tree, putting the results in leafIds
redrawFromBranch
  • 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
rotateBranch
  • branch
Reverse the order a branch's children are drawn in
saveNode
  • node
Atd a node to the tree. Used by the parsers.
selectNodes
  • nodeIds
Select the nodes specified by node ids (array or comma seperated list). N.B. all leaves must be adjacent in the tree
setFont
  • font
Change the font for the node labels
setNodeColourAndShape
  • 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
Color of the node in rgb/hex/colornames format Eg: red, rgb(255,0,0), #adadad
Shapes
  • x = star
  • s = square
  • o = circle
  • t = triangle
Size
Size of the node
setNodeSize
  • size
Set the base size of all the nodes
setRoot
  • node
Set the root node of the tree
setTextSize
  • size
Set the size of the labels
setTreeType
  • type

Hide the lables on the tree

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

Events

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
Tree.on
  • event name
  • handler
Add the specified handler to the specified event name
Tree.addListener
  • event name
  • handler
Add the specified handler to the specified event name
Top

Events

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

PhyloCanvas.Branch

Properties

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
Top

Branch - Functions

Function Parameters Description
addChild
  • node
Add a child branch to this branch
clicked
  • 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
parseNwk
  • nwk_string
  • idx
Recursive parsing function for a Newick formatted tree file
parseLabel
  • 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
setHighlighted
  • true/false
Sets whether or not this branch is highlighted
setSelected
  • 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
Top

PhyloCanvas.History

The history panel of sub-trees

Properties

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

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
createDiv
  • 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
addSnapshot
  • 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
goBackTo
  • event
Click handler for the snapshots that removes the subsequent history entries.
Top

PhyloCanvas.ContextMenu

Properties

Properties Description
elements Menu choices, an array of dictionaries with properties
text
The label of the menu item
handler
The function in the Tree object that the menu item invokes. If a node has been clicked on it is padded to the handler
internal
Does this function apply to an internal node
leaf
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
  }]
});

Top

ContextMenu - Functions

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