contMap: Map continuous trait evolution on the tree

View source: R/contMap.R

contMapR Documentation

Map continuous trait evolution on the tree

Description

Projects the observed and reconstructed values of a continuous trait onto the edges of a tree using a color gradient.

Usage

contMap(tree, x, res=100, fsize=NULL, ftype=NULL, lwd=4, legend=NULL,
   lims=NULL, outline=TRUE, sig=3, type="phylogram", direction="rightwards", 
   plot=TRUE, ...)
## S3 method for class 'contMap'
plot(x, ...)
errorbar.contMap(obj, ...)

Arguments

tree

object of class "phylo".

x

a numerical vector of phenotypic trait values for species. names(x) should contain the species names and match tree$tip.label. Or, for plot.contMap, an object of class "contMap".

res

resolution for gradient plotting. Larger numbers (to a point) indicate a finer (smoother) gradient.

fsize

relative font size - can be a vector of length 2 in which the first element gives the font size for the tip labels & the second element giving the font size for the legend.

ftype

font type - see options in plotSimmap. As with fsize, this can be a vector with the second element giving font type for the legend.

lwd

line width for branches. Can be a single integer number or a vector. In the latter case, the second number will be taken to be the desired legend width.

legend

if FALSE no legend is plotted; if a numeric value, it gives the length of the legend in units of branch length. Default is 0.5 times the total tree length.

lims

range for the color map. By default, this will be c(min(x),max(x)), and should always include this range.

outline

logical value indicating whether or not to outline the branches of the tree in black.

sig

the number of decimal places to show on the legend limits.

type

type of plot desired. Options are "phylogram" for a rightward square phylogram; and "fan" for a circular phylogram.

direction

plotting direction for type="phylogram".

plot

logical value indicating whether or not to plot the tree. If plot=FALSE then an object of class "contMap" will be returned without plotting.

obj

object of class "contMap".

...

optional arguments for plot.contMap which include all the arguments of contMap except for tree, x, res, and lims. Also method, "fastAnc", "anc.ML", or "user" (for user-supplied states) specifying which function to use for ancestral state estimation; hold specifies whether or not to hold output to graphical device before plotting (defaults to hold=TRUE); and anc.states a vector containing some or multiple ancestral user-supplied ancestral states at nodes. Some other plotting arguments, such as xlim and ylim, may also work. Optional arguments for errorbar.contMap include x, a vector containing the original trait values mapped onto the tree (otherwise these will be obtained from obj), scale.by.ci, a logical argument (defaulting to TRUE) that determines whether or not the length of the error bars will be scaled by the CI width, and lwd, which determines the line width of the plotted error bars.

Details

Function plots a tree with a mapped continuous character.

The mapping is accomplished by estimating states at internal nodes using ML with fastAnc, and then interpolating the states along each edge using equation [2] of Felsenstein (1985). This makes these interpolated values equal to the maximum likelihood estimates under a Brownian evolutionary process.

The default color palette is not recommended as it is not colorblind friendly and does not render well into gray scale; however, this can be updated using the helper function setMap.

errorbar.contMap adds error bars to an existing plot.

Value

Plots a tree. An object of class "contMap" is returned invisibly.

errorbar.contMap adds colorful error bars to a plotted tree.

Author(s)

Liam Revell liam.revell@umb.edu

References

Felsenstein, J. (1985) Phylogenies and the comparative method. American Naturalist, 125, 1-15.

Revell, L. J. (2013) Two new graphical methods for mapping trait evolution on phylogenies. Methods in Ecology and Evolution, 4, 754-759.

Revell, L. J. (2014) Graphical methods for visualizing comparative data on phylogenies. Chapter 4 in Modern phylogenetic comparative methods and their application in evolutionary biology: Concepts and practice (L. Z. Garamszegi ed.), pp. 77-103.

Revell, L. J. (2024) phytools 2.0: an updated R ecosystem for phylogenetic comparative methods (and other things). PeerJ, 12, e16505.

Revell, L. J., K. Schliep, E. Valderrama, and J. E. Richardson (2018) Graphs in phylogenetic comparative analysis: Anscombe's quartet revisited. Methods in Ecology and Evolution, 9, 2145-2154.

See Also

anc.ML, densityMap, fastAnc, plotSimmap

Examples

## load data from Garland et al. (1992)
data(mammal.tree)
data(mammal.data)
## extract character of interest
ln.bodyMass<-log(setNames(mammal.data$bodyMass,
    rownames(mammal.data)))
## create "contMap" object
mammal.contMap<-contMap(mammal.tree,
    ln.bodyMass,plot=FALSE,res=200)
## change color scheme
mammal.contMap<-setMap(mammal.contMap,
    c("white","#FFFFB2","#FECC5C","#FD8D3C",
    "#E31A1C"))
plot(mammal.contMap,fsize=c(0.7,0.8),
    leg.txt="log(body mass)")
par(mar=c(5.1,4.1,4.1,2.1)) ## reset margins to default

phytools documentation built on June 22, 2024, 10:39 a.m.