plot.mapping: "Map" a trait: plot its distribution over a phylogenetic tree

In jacobmaugoust/ULT: Useful Little Things

"Map" a trait: plot its distribution over a phylogenetic tree

Description

This function plots continuous and discrete trait onto a phylogenetic tree, with values being either on taxa (tips/nodes) or on branches. It is largely a wrapper of the function contMap for the continous "mapping" and of the function plot.phylo for the discrete "mapping".

Usage

plot.mapping(tree,values,type=c("taxa","branch"),cols.args,title=NULL,lims=NULL,
             order=c("phylo","names","edge"),branch.col.freqs=NULL,branch.col.freqs.type=c("width","proportion"),
             mapping.args=NULL)

Arguments

tree	The phylogenetic tree to "map" the trait on
values	The (univariate) data to "map" onto the phylogenetic tree
type	The unit the values to plot do represent: either these values stand for branches (type="branch"), or they stand for taxa (type="taxa").
cols.args	The colors to use to represent the values. This can be a character vector specifying all colors to use: if type="branch", there should be as many colors as branches, and if type="taxa", there should be as many colors as is the resolution of the continuous plot by contMap (1000 by default) plus 1. This can also be a list of arguments to be used to attribute given colors to be passed to discrete.palette or scale.palette (depending if the trait is discrete or continuous, respectively); in any case, the list should at least include a "cols" vector of desired colors and a "fun" vector specifying the function to use ("discrete.palette" or "scale.palette"). If type="branch", a simple vector of colors can be provided, and the values are splitted in as many case as there are colors minus one (the latest color being for the highest values), each range being represented by a color (i.e., potentially different values with same color); it is therefore strongly advised to provide a color palette larger than the number of values in that special case. By default, it is set to a list(fun="scale.palette",cols="blue","yellow","red").
title	Optional character. To provide a title to the plot.
lims	Optional numeric. In the case of a continuous trait, the value limits to consider (two values: the inferior and superior bounds).
order	Optional character. To specify the order of the values to take into account for the "mapping". 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), according to the tree branches construction (order="edge"; branches construction is available by asking tree$edge, the numbers refering to tips and nodes), or given a custom order (order being a vector of the names or of the number of all tips/nodes and of same length than the length of values)
branch.col.freqs	Optional. If type="branch", the user may want to define custom frequencies for the colors of the branches. If branch.col.freqs="equal" (or "even" or "e"), the frequencies are equal for all colors. Otherwise, it can be a numeric specifying the proportions for each color (the sum must be equal to 1) or the values serving as steps/quantiles to define the range of values for each color.
branch.col.freqs.type	Optional. If type="branch" and non-null branch.col.freqs, if the frequencies are relative (not values serving as limits/quantiles), the user may want to have ranges of equal width between limits (branch.col.freqs.type="width") or of equal proportion of individuals (branch.col.freqs.type="proportion").
mapping.args	Optional list. List of arguments to take into account for the "mapping". Depending on the type of trait, these arguments are either to be passed to plot.phylo (for discrete trait) or to contMap (for continuous trait)

Examples

require(ape)
require(phytools)
# Get a random tree
set.seed(1)
tree<-rtree(30)

# Work with a continuous trait on all taxa
## Get a random continuous trait
set.seed(2)
tips<-fastBM(tree)
## Get ancestral states of it
ancs<-ace(tips,tree,"continuous","REML")$ace
## Collate both
x<-c(tips,ancs) # As it is, it is a vector with tip values then node values, so sorted "phylogenetically", according to tips and nodes order
## Plot the trait using a gradual color palette with blue, yellow, and red (the default)
plot.mapping(tree,x,"taxa",cols.args=list(fun="scale.palette",cols=c("blue","yellow","red")))
## Plot the trait using a gradual color palette with blue, green, and pink
plot.mapping(tree,x,"taxa",cols.args=list(fun="scale.palette",cols=c("blue","green3","pink")))
## Plot the trait with a title
plot.mapping(tree,x,"taxa",title="mapping of continuous x")
## Plot the trait with a legend bar
plot.mapping(tree,x,"taxa",mapping.args=list(legend=TRUE))
## Plot the trait with different lims, setting the start at 0 (so that all values below zero should be blue)
plot.mapping(tree,x,"taxa",lims=c(0,max(x)),mapping.args=list(legend=TRUE))
## Sort the values in an odd way to rely on names and plot the mapping
plot.mapping(tree,x,"taxa",title="reference") # The reference mapping
tree$node.label<-as.character((1:Nnode(tree))+Ntip(tree)) # Add node labels so that they match the names of x
plot.mapping(tree,x[sample(c(1:length(x)),length(x))],"taxa",order="names",title="with names") # With alphabetically sorted values
## Sort the values in an odd but given way
custom.sort<-sample(1:length(x),length(x))
plot.mapping(tree,x[custom.sort],"taxa",order=names(x)[custom.sort],title="custom sorting with names") # With custom sorting on names (implies that both the three and the values have tip and node labels)
plot.mapping(tree,x[custom.sort],"taxa",order=custom.sort,title="custom sorting") # With custom sorting
tree$node.label<-NULL
plot.mapping(tree,x[custom.sort],"taxa",order=custom.sort,title="custom sorting with no names") # With custom sorting not being able to rely at all on names since tree has no node labels anymore

# Work with a discrete trait on all taxa
## Get a random discrete trait
set.seed(3)
tips<-round(fastBM(tree),0)
## Get ancestral states of it
ancs<-apply(ace(tips,tree,"discrete")$lik.anc,1,function(x){sort(unique(tips))[which.max(x)]})
## Collate both
x<-c(tips,ancs) # As previously, it is sorted "phylogenetically" as it is now
## Plot the trait
plot.mapping(tree,x,"taxa",cols.args=list(fun="discrete.palette",cols=contrasting.palette(length(unique(x))),ncols=1001))
legend("topright",legend=sort(unique(x)),lwd=2,col=contrasting.palette(length(unique(x))),bty="n")
## To check color distribution with values
x
nodelabels()

# Work with a trait on branches
## Get a random continuous trait
set.seed(4)
tips<-fastBM(tree)
## Get ancestral states of it
ancs<-ace(tips,tree,"continuous","REML")$ace
## Collate both
trait<-c(tips,ancs)
## Get a gradient of colors according to these values
cols.args<-scale.palette(ncols=1001,cols=c("blue","yellow","red"),middle=NA,middle.col=NA,span=range(trait))
## Plot it
plot.mapping(tree,trait,cols.args=cols.args,mapping.args=list(legend=TRUE))
## Get trait value changes over each branch (in the order of the tree$edge element)
x<-apply(tree$edge,1,function(x){trait[x[2]]-trait[x[1]]})
## Plot the trait value changes with the same color gradient than for the trait values themselves
plot.mapping(tree,x,"branch",cols.args=cols.args,order="edge")
## Plot the trait value changes by simply splitting them in three colors (the lower half of the changes being in blue, the second in yellow, and the highest value in red)
plot.mapping(tree,x,"branch",cols.args=c("blue","yellow","red"),order="edge",branch.col.freqs = "equal")
## Playing a bit with the options regarding branch color frequencies
plot.mapping(tree,x,"branch",cols.args=c("blue","yellow","red"),order="edge",title="reference")
### Changing proportion of colors of branches: ranges of same width between values limits
plot.mapping(tree,x,"branch",cols.args=c("blue","yellow","red"),order="edge",branch.col.freqs = "equal",branch.col.freqs.type="width",title="equal range widths between limits")
tiplabels(round(x[tree$edge[,2]<=Ntip(tree)],2),adj=-0.25,frame = "none",cex=0.75)
nodelabels(c("",round(x[tree$edge[,2]>Ntip(tree)],2)),adj=-0.25,frame = "none",cex=0.75)
setNames(seq(min(x),max(x),length.out=4),c("","blue","yellow","red"))
### Changing proportion of colors of branches: same proportion of individuals between values limits
plot.mapping(tree,x,"branch",cols.args=c("blue","yellow","red"),order="edge",branch.col.freqs = "equal",branch.col.freqs.type="proportion",title="range widths with same proportion of values")
tiplabels(round(x[tree$edge[,2]<=Ntip(tree)],2),adj=-0.25,frame = "none",cex=0.75)
nodelabels(c("",round(x[tree$edge[,2]>Ntip(tree)],2)),adj=-0.25,frame = "none",cex=0.75)
setNames(quantile(x,seq(0,1,1/3)),c("","blue","yellow","red"))
### Changing proportion of colors of branches: custom proportional width ranges
plot.mapping(tree,x,"branch",cols.args=c("blue","yellow","red"),order="edge",branch.col.freqs = c(0.3,0.1,0.6),branch.col.freqs.type="width",title="range of custom widths between limits")
tiplabels(round(x[tree$edge[,2]<=Ntip(tree)],2),adj=-0.25,frame = "none",cex=0.75)
nodelabels(c("",round(x[tree$edge[,2]>Ntip(tree)],2)),adj=-0.25,frame = "none",cex=0.75)
setNames(c(min(x)+c(0,0.3,0.4,1)*diff(range(x))),c("","blue","yellow","red"))
### Changing proportion of colors of branches: custom proportions of values
plot.mapping(tree,x,"branch",cols.args=c("blue","yellow","red"),order="edge",branch.col.freqs = c(0.3,0.1,0.6),branch.col.freqs.type="proportion",title="range of custom widths between limits")
tiplabels(round(x[tree$edge[,2]<=Ntip(tree)],2),adj=-0.25,frame = "none",cex=0.75)
nodelabels(c("",round(x[tree$edge[,2]>Ntip(tree)],2)),adj=-0.25,frame = "none",cex=0.75)
setNames(quantile(x,c(0,0.3,0.4,1)),c("","blue","yellow","red"))
### Changing proportion of colors of branches: custom steps, i.e., ranges with custom values between each color range
plot.mapping(tree,x,"branch",cols.args=c("blue","yellow","red"),order="edge",branch.col.freqs = c(-1,1),title="Values splitted in three ranges with custom internal bounds between them")
tiplabels(round(x[tree$edge[,2]<=Ntip(tree)],2),adj=-0.25,frame = "none",cex=0.75)
nodelabels(c("",round(x[tree$edge[,2]>Ntip(tree)],2)),adj=-0.25,frame = "none",cex=0.75)
setNames(c(min(x),-1,1,max(x)),c("","blue","yellow","red"))
## Playing a bit with the options regarding the sorting of the values
### Sorting according to phylogeny (order of tips and nodes)
plot.mapping(tree,x[order(tree$edge[,2])],"branch",cols.args=c("blue","yellow","red"),order="phylo",title="phylo sorting")
### Sorting according to taxa labels
tree$node.label<-as.character((1:Nnode(tree))+Ntip(tree)) # Assigning node labels
plot.mapping(tree,setNames(x,c(tree$tip.label,tree$node.label)[tree$edge[,2]]),"branch",cols.args=c("blue","yellow","red"),order="names",title="with names, no sorting")
custom.order<-sample(1:length(x),length(x))
plot.mapping(tree,setNames(x,c(tree$tip.label,tree$node.label)[tree$edge[,2]])[custom.order],"branch",cols.args=c("blue","yellow","red"),order="names",title="with names, custom sorting 1")
plot.mapping(tree,setNames(x,c(tree$tip.label,tree$node.label)[tree$edge[,2]])[custom.order],"branch",cols.args=c("blue","yellow","red"),order=c(tree$tip.label,tree$node.label)[tree$edge[,2]][custom.order],title="with names, custom sorting 2")
tree$node.label<-NULL
plot.mapping(tree,x[custom.order],"branch",cols.args=c("blue","yellow","red"),order=custom.order,title="no names, custom sorting")

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