thermo.var: Add "thermometers" of trait variation across reconstruction...

In jacobmaugoust/ULT: Useful Little Things

Add "thermometers" of trait variation across reconstruction methods for phylogenetic taxa

Description

This function adds "thermometers" like the nodelabels and tiplabels functions. However, these functions only add discrete "thermometers", whereas one can want to draw a gardient of values. This is doable by using the nodelabels and tiplabels functions, but one has to provide a large matrix of values and a large array of colors (with very small steps) to obtain a continuous-like "thermometer". This function aims to simplify this process, only needing tree, values, and options about the palette of colors to use. This is especially useful when "mapping" at once a continuous trait over a tree according to several methods, in order to get an idea of the local (i.e., taxon-level) variation of the reconstructions. By default, the function considers that a previous mapping has been done and that it aims to do "summarize" various methods; this is considered here by calculating the arithmetic mean value of all methods for each taxon (the median could be inadequate if the number of methods is small). By default, no thermometer is reconstructed for taxa with values that are equal for each method (like ancestral reconstructions of tips.

Usage

thermo.var(tree,values,cols.args,thermo.lims=c("global","local","asym","sym0","symx"),
           resolution=100,order=c("phylo","names"),aggr=TRUE,
           aggr.bar=TRUE,aggr.bar.col=c("adaptative","blackwhite","black","anycolor"),
           root.value=FALSE,border=FALSE,cex=NULL,width=NULL,height=NULL,adj=c(0.5,0.5))

Arguments

tree	The phylogenetic tree to put "thermometers" on
values	The data the colors have to follow; can be a data frame or a matrix with taxa as rows and methods as columns.
cols.args	Optional list. A list of arguments for the reference color palette to be passed to the scale.palette function. These arguments are the palette resolution ncol, the colors to consider col, the central color middle.col if there is (otherwise turning this to NA), a central value in the values range middle (if there is, otherwise turning this to NA), and the values steps to follow steps (if there are, otherwise turning this to NA). Of these, the parameters ncol and cols are the most important; the parameters middle.col and middle can be left empty, and the parameter span is estimated as the range of values if left empty. By default, a "blue-yellow-red" palette of resolution 100 is computed.
thermo.lims	Optional. Upper and lower limits of values to be considered for the global tree-level color palette. Can be a character to set to the range of plotted values only (lims="local"; the average of all methods) or of all values (lims="global") asymmetrically (taking natural values range, "asy"), symmetrically around zero (taking further value from zero and its opposite, "sym0"), or around another value ("symx", the arithmetic mean by default); hence it can be a vector of length 1 (choosing limits across or within variables), 2 (adding the asymmetric or symmetric choice), or 3 (adding the central value if symmetric to a given value). Otherwise, a numeric of length 2 explicitly specifying values to take as limits.
resolution	Optional numeric. The resolution of the gradient of each "thermometer", i.e., the number of steps (and of successive colors). By default set to 100.
order	Optional character. To specify the order of the values. Default is to consider that values are sorted in the tips/nodes order (order="phylo"; 1-Ntip rows of values being for tips 1-N, and so on for the nodes). Values can also be sorted depending on their names (order="names"; if the tree AND the values have names for tips AND nodes) or given a custom order (order being a vector of the names of all tips/nodes of same length than the number of rows of values)
aggr	Optional. The reference values column for the "aggregated" variable (i.e., the variable taking into account all methods by taking the arithmetic mean of all values for each taxon) that represents the center of the color palette (but not necessarily of the "thermometers"!). The values data can already contain it as being the last column (aggr=TRUE, the default), as being absent (aggr=FALSE, computed by the function), as being one of the columns but no the last one (aggr being the column name or number refering to it in values).
aggr.bar	Optional logical. Whether to plot a horizontal bar in the "thermometer" to highlight the position of the aggregated value on the "thermometer" of each taxon (the mean not being necessarily in the middle). Default is set to TRUE
aggr.bar.col	Optional character. If a horizontal bar is drawn for the position of the "aggregated" value, it can be of several colors. By default, it is the RGB inverse (negative) of the aggregated color (aggr.col="adaptative"), but it can also be the further black or white color to the aggregated color (aggr.col="blackwhite"), a single color to use for all "thermometers", or a vector of colors to use for all "thermometers" (with one color for each, the vector being recycled if being of different length than the number of rows of values)
root.value	Optional logical. A value for the root is not always available. This can be specified if there is a root value (root.value=TRUE) or not (root.value=FALSE, the default)
border	Optional logical. Whether to plot a black border for "thermometer"s if set to TRUE or not if set to FALSE (the default)
cex	Optional numeric. The global size ('Character EXpansion'; see the nodelabels and tiplabels help pages) of the "thermometers"
width	Optional numeric. The width of the "thermometers" (see the nodelabels and tiplabels help pages)
height	Optional numeric. The height of the "thermometers" (see see the nodelabels and tiplabels help pages)
adj	Optional numeric. The horizontal and vertical position of the "thermometers" relative to the taxa (see see the nodelabels and tiplabels help pages)

Examples

require(ape)
require(phytools)
# Get a random tree
set.seed(2)
tree<-rtree(30)
# Get a random distribution of values for tips
tipvalues<-matrix(ncol=5,nrow=Ntip(tree))
set.seed(2)
tipvalues[,1]<-fastBM(tree)
# Modify a bit these values, with about one half of variation, to simulate different methods
for(i in 2:5){
  set.seed(i+1)
  tipvalues[,i]<-sapply(tipvalues[,1],function(x){x+runif(1,-0.5,0.5)*diff(range(tipvalues[,1]))})
}
rownames(tipvalues)<-tree$tip.label
# Get the ancestral reconstructions for each "method"
ancvalues<-matrix(ncol=5,nrow=Nnode(tree))
for(i in 1:5){
  set.seed(i)
  ancvalues[,i]<-fastAnc(tree,tipvalues[,i])
}
# Collate tips and nodes values
values<-rbind(tipvalues,ancvalues)
# Get average values for each taxon
values<-cbind(values,"aggr"=apply(values,1,mean))
# Do a continuous mapping of the "methods" average
plot.mapping(tree,values[,6],title="'negative' aggr bars")
# Add simple "thermometers", just specifying the tree, the values, and that there is a value for the root
thermo.var(tree,values,root.value=TRUE)
# Modify the horizontal bars showing the average values so that they are in black or white
plot.mapping(tree,values[,6],title="black/white aggr bars")
thermo.var(tree,values,root.value=TRUE,aggr.bar.col="blackwhite")
# One can notice that the color of the "thermometer" the bar is at is not necessarily the same than the one used for the mapping; this is because the range of average values is not necessarily the same than the range of all values (i.e., including extreme cases smoothed by averaging values)
# Re-plot the mapping with a range of colors based on aggregated values only (left) and on all dataset values (righ) and add "thermometers"
par(mfrow=c(1,2))
plot.mapping(tree,values[,6],lims=range(values[,6]),title="with aggr limits for map")
thermo.var(tree,values,root.value=TRUE,aggr.bar.col="blackwhite",border=TRUE)
plot.mapping(tree,values[,6],lims=range(values),title="with global limits for map")
thermo.var(tree,values,root.value=TRUE,aggr.bar.col="blackwhite",border=TRUE)
par(mfrow=c(1,1))

# Now play a bit with the options
## Without bar for the average values
plot.mapping(tree,values[,6],title="without aggr bar")
thermo.var(tree,values,root.value=TRUE,aggr.bar=FALSE)
## With average values-only color palette AND with "thermometers" indexed on that one
## (plus playing with relative horizontal position of "thermometers")
plot.mapping(tree,values[,6],title="with thermos whose limits are those of all values (left) and mapping values (right)")
thermo.var(tree,values,root.value=TRUE,thermo.lims="global",adj=0.45) # "Thermometers" with all-methods range as limits
thermo.var(tree,values,root.value=TRUE,thermo.lims="local",adj=0.5) #"Thermometers" with aggregated method range as limits
## With average values-only color palette for mapping AND "thermometers"
plot.mapping(tree,values[,6],title="aggr colors, no aggr bar",lims=range(values[,6]))
thermo.var(tree,values,root.value=TRUE,aggr.bar=FALSE,thermo.lims = "local")
## With global values color palette for mapping AND "thermometers"
plot.mapping(tree,values[,6],title="global colors, no aggr bar",lims=range(values))
thermo.var(tree,values,root.value=TRUE,aggr.bar=FALSE,thermo.lims = "global")
## Modify colors palette
plot.mapping(tree,values[,6],cols=list(fun="scale.palette",cols=c("blue","green3","pink")),title="with other colors",lims=range(values))
thermo.var(tree,values,root.value=TRUE,cols.args=list(cols=c("blue","green3","pink")))
## Modify thermo resolution to something very extreme
plot.mapping(tree,values[,6],title="with low resolution of 'thermometers' (e.g., tips t15 or t7)")
thermo.var(tree,values,root.value=TRUE,resolution=3)
## Specify aggr column
plot.mapping(tree,values[,6],title="specifying aggr column")
thermo.var(tree,values,root.value=TRUE,aggr=6)
## Compute it during function execution
plot.mapping(tree,values[,6],title="running aggr during function")
thermo.var(tree,values[,1:5],root.value=TRUE,aggr=FALSE)
## Sort values by their names and specify it
tree$node.label<-as.character((1:Nnode(tree))+Ntip(tree)) # Add node labels if wanting to rely on names
rownames(values)<-c(tree$tip.label,tree$node.label)
plot.mapping(tree,values[,6],title="sorting with names")
thermo.var(tree,values[sample(1:nrow(values),nrow(values)),],root.value=TRUE,order="names")
## Sort values with an arbitrary order of taxa labels and specify it
plot.mapping(tree,values[,6],title="custom label sorting")
set.seed(1)
custom.order<-sample(1:nrow(values),nrow(values))
thermo.var(tree,values[custom.order,],root.value=TRUE,order=c(tree$tip.label,tree$node.label)[custom.order])
## Sort values with an arbitrary order of taxa and specify it
plot.mapping(tree,values[,6],title="custom sorting")
thermo.var(tree,values[custom.order,],root.value=TRUE,order=custom.order)
tree$node.label<-NULL
rownames(values)<-c(tree$tip.label,rep("",Nnode(tree)))
plot.mapping(tree,values[,6],title="custom sorting without node names")
thermo.var(tree,values[custom.order,],root.value=TRUE,order=custom.order)
## Making "thermometers" a bit bigger
plot.mapping(tree,values[,6],title="big thermometers")
thermo.var(tree,values,root.value=TRUE,cex=2)
## Making "thermometers" a bit wider
plot.mapping(tree,values[,6],title="wide thermometers")
thermo.var(tree,values,cols.args=list(cols=c("blue","yellow","red")),root.value=TRUE,width=0.15)
## Making "thermometers" a bit higher
plot.mapping(tree,values[,6],title="tall thermometers")
thermo.var(tree,values,cols.args=list(cols=c("blue","yellow","red")),root.value=TRUE,height=3)

jacobmaugoust/ULT documentation built on May 16, 2023, 1:29 p.m.