dotTree with trait column labels

Today a colleague emailed me the following request:

I have a quick phytools question. Is it possible to add trait labels above each dot column with the dotTree function? I'm thinking something similar to labels=TRUE with phylo.heatmap. I'm plotting 40-ish discrete characters next to a tree and would like to be able to ID each one with a label.

This was not, in fact, implemented as an option in the function dotTree (which, truth be told, is not that flexible); however, it could be easily added & it makes sense to include, so I did that.

Here's a quick demo using simulated continuous & discrete character traits:

## continuous traits
tree

## 
## Phylogenetic tree with 20 tips and 19 internal nodes.
## 
## Tip labels:
##  t7, t9, t10, t6, t17, t18, ...
## 
## Rooted; includes branch lengths.

head(X)

##     trait 1 trait 2 trait 3 trait 4 trait 5 trait 6 trait 7 trait 8
## t7  -0.4714  1.5283  0.2456  1.9166 -1.4017 -2.3089  0.9481  1.3552
## t9   0.6897 -0.1315 -2.5255  1.2014  1.3690 -2.0750  1.0875  1.3529
## t10  2.1341  0.9865 -1.2671  1.3842  1.4866 -1.9995  1.7009  1.3826
## t6   1.0728  1.6496 -1.6141  1.3739 -0.7777 -1.4978  1.2193  1.4542
## t17 -0.8300 -2.9037 -1.3690  1.2321  1.4352 -1.9980  0.0441 -0.4903
## t18 -1.0488 -2.2984 -2.2619  1.1572  0.4136 -1.3016  0.2999 -0.2668
##     trait 9 trait 10 trait 11 trait 12 trait 13 trait 14 trait 15 trait 16
## t7   1.5764  -3.0724  -0.0816   1.4169  -2.8047  -3.0776  -0.8453   0.0275
## t9   0.9509  -3.4436  -0.0688   0.5440   0.7249   0.1317  -0.3983  -1.1296
## t10  0.4051  -4.5642   0.1199   1.5433  -0.7812  -2.2066  -2.0350  -0.9623
## t6   0.7027  -1.8926   0.6281   1.3586  -1.7321  -1.2361  -2.0213  -0.2975
## t17 -0.0327  -1.1327   0.8425  -0.4366   0.2869  -2.0729  -1.8808   1.3946
## t18 -0.1935  -1.1762   1.2312   0.1660   1.0669  -0.8144  -1.4572   0.6310
##     trait 17 trait 18 trait 19 trait 20
## t7   -0.5724   1.2826   1.4015   2.2016
## t9   -2.2081  -0.0976   0.5643   0.5123
## t10  -1.1510   1.8682   1.1768  -0.5897
## t6   -2.5253   0.9187  -0.5451  -1.3768
## t17  -0.7521   1.4511  -1.2810  -0.9553
## t18  -0.7357   1.4933  -0.2726  -0.1514

## first default mode
dotTree(tree,X)

## now with trait column labels
dotTree(tree,X,labels=TRUE,length=8) ## also change legend length

Note that the function uses the column names from our input data matrix, so if we want to change the trait names, we just have to change these.

Now discrete traits:

head(Y)

##     V1 V2 V3 V4 V5 V6 V7 V8 V9 V10 V11 V12 V13 V14 V15 V16 V17 V18 V19 V20
## t7   c  a  a  a  a  c  b  a  c   c   a   a   b   c   b   b   b   a   a   a
## t9   b  b  a  b  c  b  b  a  b   b   b   a   a   b   b   b   b   a   a   c
## t10  c  a  c  c  a  b  a  b  a   c   b   a   a   c   c   b   a   a   b   a
## t6   b  c  c  b  b  c  a  a  a   c   a   a   b   b   b   a   c   a   c   b
## t17  b  b  b  a  a  c  a  c  a   c   b   c   a   b   a   b   c   a   b   a
## t18  c  b  a  a  b  c  a  c  a   a   b   b   a   b   a   b   c   a   b   b
##     V21 V22 V23 V24 V25 V26 V27 V28 V29 V30
## t7    c   c   b   a   a   c   b   b   b   b
## t9    a   c   c   b   c   c   b   b   b   a
## t10   a   a   c   c   a   b   b   b   a   a
## t6    a   c   c   c   b   b   b   a   a   b
## t17   b   c   a   b   c   c   c   b   a   b
## t18   c   c   a   a   c   c   c   b   a   b

dotTree(tree,Y,labels=TRUE)

## change the color scheme
cols<-setNames(RColorBrewer::brewer.pal(n=3,"Accent"),
    unique(as.vector(sapply(Y,levels))))
cols

##         a         b         c 
## "#7FC97F" "#BEAED4" "#FDC086"

dotTree(tree,Y,labels=TRUE,colors=cols)

Note how the order of the legend is changed to match the order of our custom color palette.

BTW, the tree & data were simulated as follows:

library(phytools)
tree<-pbtree(n=20)
X<-round(fastBM(tree,nsim=20),4)
colnames(X)<-paste("trait",1:ncol(X))
Q<-matrix(c(-1,1,0,1,-2,1,0,1,-1),3,3,
    dimnames=list(letters[1:3],letters[1:3]))
Y<-sim.Mk(tree,Q,nsim=30)