New version of plotBranchbyTrait with full user control of plotting options

Today I received the following request from a colleague regarding the phytools function plotBranchbyTrait:

A PhD student of mine is trying to use your function plotBranchbyTrait to plot a phylogeny where the branch colors reflect the rate of molecular evolution .... He has managed to plot the tree with the branch colors and that part works very nicely, but when trying to offset the tip labels (species names) or modifying the edge.width he gets a message saying that the argument "label.offset" (or "edge.width") is matched by multiple actual arguments.... Can you assist us as why you think we're getting these messages? Any tricks to offset the species names?

plotBranchbyTrait differs from other similar functions in phytools (such as densityMap and contMap) in that it requires a single input value for the mapped trait per edge, and then plots that trait value on a color gradient scale - but uniformly for each branch.

The truth is, I developed this function primarily to help a colleague - so it is not endowed with the full range of plotting options. Unlike the vast majority of tree plotting functions in phytools, this one calls plot.phylo from the ape package internally - rather than plotSimmap in phytools.

This afternoon, I took a the twenty minutes (or so) required to pass control of all* (*with the exception of a couple, such as edge.color, which don't make sense) to the user. In so doing, I've kept the non-optional arguments of plotBranchbyTrait the same, although I've changed a few of the internal defaults - just to make for nicer plots. (For instance, I discovered that the default x & y limits meant that the legend was being plotting out of bounds in many instances.)

The updated code for plotBranchbyTrait is here, but I have also posted a new version of phytools (phytools 0.2-93), which can be downloaded and installed from source. (For more information on installing packages from source, search the web.)

Here's the usual demo:

> library(phytools)
> packageVersion("phytools")
[1] ‘0.2.93’
> tree<-pbtree(n=50)
> x<-fastBM(tree)
> plotBranchbyTrait(tree,x,mode="tips",edge.width=4, prompt=TRUE)
Click where you want to draw the bar

For fun, we can compare to contMap, which interpolates smoothly along each internal & terminal edge. (Of course, plotBranchbyTrait can also be used for any arbitrary trait in which we have a state on a continuous scale at each edge of the tree.) These two plots should look very similar - it is just a matter of whether or not our eyes can easily distinguish between continuously & abruptly changing colors.

> XX<-contMap(tree,x,lims=c(-3.5,1.5))
> XX$cols[]<-rainbow(1001,start=0.7,end=0)
> plot(XX,outline=F,lwd=4,legend=0.82)

Virtually the same to my eye!