Calculating Topological Properties of Phylogenies

Tools for calculating and viewing topological properties of phylogenetic trees.

Travis-CI Build Status CRAN Status Badge CRAN Downloads

phyloTop: Calculating Topological Properties of Phylogenies

phyloTop provides tools for calculating and viewing topological properties of phylogenetic trees.

Installing phyloTop

To install the development version from github:


The stable version can be installed from CRAN using:


Then, to load the package, use:


Content overview

The key functions available in phyloTop are:

  • avgLadder: find the average ladder size in a tree

  • cherries: find the number of cherries in a tree

  • colless.phylo: find the Colless imbalance number of a tree

  • getDepths: find the depth of each node in a tree

  • ILnumber: find the number of nodes with exactly one tip child

  • ladderSizes: find the size of any "ladders" in a tree (consecutive nodes, each with exactly one tip child)

  • maxHeight: find the maximum height (equivalently, depth) of nodes in a tree

  • nConfig: find the sizes of all configurations (equivalently, clades) in a tree

  • nodeDepth: find the depth of a given node in a tree

  • nodeDepthFrac: find the fraction of nodes in a tree at a given depth

  • nodeImb: find the imbalance of a given node in a tree

  • nodeImbFrac: find the fraction of nodes in a tree with an imbalance of a given threshold or more

  • phyloTop: find a range of tree statistics for a list of trees (faster than calling each function individually)

  • pitchforks: find the number of pitchforks (clades of size three) in a tree

  • sackin.phylo: find the Sackin index of a tree

  • splitTop: find the split topology of a tree - the size of clades at a given depth

  • stairs: find the "staircase-ness" measures, as defined by Norstrom et al. 2012

  • treeImb: find the tree imbalance - the imbalance at each node

  • widths: find the number of nodes at each depth in a tree

Tree visualisation tools:

  • configShow: plot a tree, highlighting the configurations of a given size

  • ladderShow: plot a tree, highlighting the "ladders"

  • subtreeShow: plot a tree, highlighting the subtree(s) descending from the given node(s)

Simulating an epidemic and creating the corresponding genealogy:

  • makeEpiRecord: simulate an epidemiological record of infectors, infectees, infection times and recovery times

  • getLabGenealogy: create a genealogy from an epidemiological record


Tree statistics:

Apply tree statistic functions to a list of 10 random trees, each with 50 tips:


Example output:

##   avgLadder cherries colless.phylo ILnumber maxHeight pitchforks sackin.phylo   stairs1    stairs2
## 1   3.000000       19    0.11139456       12        10          8          295 0.7755102 0.01576994
## 2   3.000000       12    0.13945578       26        11          7          308 0.6734694 0.01982611
## 3   2.000000       19    0.10289116       12        10          7          289 0.5918367 0.01719111
## 4   2.750000       17    0.08758503       16         9          6          277 0.5714286 0.01921548
## 5   3.000000       19    0.06207483       12         8          7          257 0.4489796 0.02279353
## 6   2.666667       16    0.19132653       18        13          8          365 0.3877551 0.01828405
## 7   2.000000       18    0.12414966       14        11          8          306 0.9591837 0.01403966
## 8   3.000000       18    0.08758503       14        11          9          271 0.4285714 0.02308904
## 9   2.500000       14    0.15051020       22        11         11          341 0.9795918 0.01062925
## 10  2.000000       17    0.14370748       16        12          8          321 0.2244898 0.02706817

Tree visualisation tools:

Plot a random tree with 20 tips, highlighting the the clade(s) descending from nodes 23 and 35:

subtreeShow(rtree(20),nodeList=c(23,35), mainCol="navy", subtreeCol="cyan", nodeLabelCol="cyan", edge.width=2)

Example output:

example plot of subtreeShow


phyloTop v2.1.0

We are very grateful to Leonid Chindelevitch for his comments which have led to this significantly improved version of phyloTop: most of the functions are now calculated in linear time and We have fixed errors in the calculation of the sackin and stairs measures.

phyloTop v2.0.0

phyloTop v1.1.1 was archived on CRAN on 2015-10-29 as it was no longer maintained by its creator, Michael Boyd.

The package has been revived by Michelle Kendall and Caroline Colijn. All of the functions in version 2.0.0 have been updated, with faster implementations, simplified format requirements and dependencies, and further help files and examples added. We have included explanations in the help files wherever version 2.0.0 is not backwards compatible, and documented the deprecated functions.

Major updates include:

  • all functions accept trees of class phylo or phylo4, automatically changing them to class phylo and coercing them into binary, rooted trees wherever possible.

  • the functions nConfig, ladderSizes and getDepths (on which many of the others depend) have been freshly implemented and are significantly faster.

  • the new function phyloTop takes a list of trees and applies a variety of topological functions, returning a matrix of topological statistics (faster than calling each function individually). Other new functions are: makeEpiRecord, nodeImbFrac, nodeDepthFrac, phyloCheck.

  • many minor functions were only called by one main function - these have been deprecated and subsumed into the code for the main function. Some minor functions are unnecessary now that compuations are performed on trees in phylo rather than phylo4 format - these have been deprecated. Others have been updated and marked as internal.

  • the functions avgLadder, cherries, ILnumber, maxHeight, pitchforks, and sackin.phylo now contain normalisation options. We thank Giacomo Plazzotta for enabling this by providing their maximum values.

  • errors arising from submitting a tree with two tips have now been removed. We thank Scott Ward for spotting this problem and supplying code fixes.

  • further plotting options have been added to the tree visualisation functions configShow, ladderShow and subtreeShow.

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.


2.1.1 by Michelle Kendall, 3 years ago

Browse source code at

Authors: Michelle Kendall [aut, cre] , Michael Boyd [aut] , Caroline Colijn [aut]

Documentation:   PDF Manual  

Task views: Phylogenetics, Especially Comparative Methods

GPL-2 license

Imports igraph, methods, NHPoisson, phylobase

Depends on ape

Suggests testthat

See at CRAN