densityMap: Plot posterior density of stochastic mapping on a tree

Description

Visualize posterior probability density from stochastic mapping using a color gradient on the tree.

Usage

densityMap(trees, res=100, fsize=NULL, ftype=NULL, lwd=3, check=FALSE,
   legend=NULL, outline=FALSE, type="phylogram", direction="rightwards",
   plot=TRUE, ...)
# S3 method for densityMap
plot(x, ...)

Value

Plots a tree and returns an object of class "densityMap" invisibly.

Arguments

trees: set of phylogenetic trees in a modified "multiPhylo" object. Values for a two-state discrete character are mapped on the tree. See make.simmap and read.simmap for details.
res: resolution for gradient plotting. Larger numbers indicate a finer (smoother) gradient.
fsize: relative font size - can be a vector with the second element giving the font size for the legend.
ftype: font type - see options in plotSimmap. As with fsize, can be a vector with the second element giving font type for the legend.
lwd: line width for branches. If a vector of two elements is supplied, the second element will be taken to be the desired width of the legend bar.
check: check to make sure that the topology and branch lengths of all phylogenies in trees are equal.
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.
outline: logical value indicating whether or not to outline the branches of the tree in black.
type: type of plot desired. Options are "phylogram" for a rightward square phylogram; and "fan" for a circular phylogram.
plot: logical value indicating whether or not to plot the tree. If plot=FALSE then an object of class "densityMap" will be returned without plotting.
direction: plotting direction for type="phylogram".
x: for plot.densityMap, an object of class "densityMap".
...: optional arguments for plot.densityMap. These include all the arguments of densityMap except trees and res. Additional optional arguments include mar (margins), offset (tip label offset: in units of the edge length or character widths, as in plotSimmap), and hold (whether or not to use dev.hold to hold output to graphical device before plotting; defaults to hold=TRUE). Also, the argument states can be used to 'order' the states on the probability axis (that is, which state should correspond to a posterior probability of 0 or 1). Some other plotting arguments, such as xlim and ylim, may also work.

Author

Liam Revell liam.revell@umb.edu

Details

Function plots a tree with the posterior density for a mapped character from stochastic character mapping on the tree. Since the mapped value is the probability of being in state "1", only binary [0,1] characters are allowed.

References

Bollback, J. P. (2006) Stochastic character mapping of discrete traits on phylogenies. BMC Bioinformatics, 7, 88.

Huelsenbeck, J. P., R. Neilsen, and J. P. Bollback (2003) Stochastic mapping of morphological characters. Systematic Biology, 52, 131-138.

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. (2024) phytools 2.0: an updated R ecosystem for phylogenetic comparative methods (and other things). PeerJ, 12, e16505.

Examples

Run this code

## load tree and data from Revell & Collar (2009)
data(sunfish.tree)
data(sunfish.data)

## extract discrete character (feeding mode)
fmode<-setNames(sunfish.data$feeding.mode,
    rownames(sunfish.data))
	 
## fit discrete character models
sunfish_er<-fitMk(sunfish.tree,fmode,model="ER")

## do stochastic mapping
smap.trees<-simmap(sunfish_er)

## compute "densityMap" object
sunfish.dmap<-densityMap(smap.trees,plot=FALSE,
    res=100)
	
## re-color
sunfish.dmap<-setMap(sunfish.dmap,hcl.colors(n=10))

## plot density map
plot(sunfish.dmap,lwd=5,outline=TRUE)

## reset margins to default
par(mar=c(5.1,4.1,4.1,2.1))

Run the code above in your browser using DataLab