cohorts: Visualize macroevolutionary cohorts

Description

Plots the matrix of pairwise correlations in rate regimes between all tips in a phylogeny.

Usage

cohorts(
  x,
  ephy,
  col,
  pal,
  lwd = 1,
  ofs = 0,
  use.plot.bammdata = FALSE,
  useraster = FALSE,
  LARGE = 500,
  ...
)

Arguments

x: A matrix of pairwise correlations generated by getCohortMatrix.
ephy: An object of class bammdata.
col: A vector of colors passed to the function image. These will be used to color the values in x. See documentation for image. If col = 'temperature', the color palette from rich.colors from the gplots package will be used.
pal: The palette to use if use.plot.bammdata=TRUE. See options documented in the help file for plot.bammdata.
lwd: A numeric indicating the width of branches in the phylogeny.
ofs: A numeric controlling the offset of the phylogeny from the matrix plot. Appropriate values will probably be in the interval [0,0.1].
use.plot.bammdata: Logical. should a phylorate plot be generated?
useraster: A logical indicating whether the function image should plot the matrix as a raster.
LARGE: An integer. If trees have more tips than LARGE, useraster will be coerced to TRUE.
...: Further arguments passed to plot.bammdata if use.plot.bammdata=TRUE or plot.phylo if use.plot.bammdata=FALSE.

Author

Mike Grundler

Details

The plotting function creates an image of the BAMM correlation matrix between tip lineages of the phylogeny. Each correlation is the posterior frequency with which a pair of lineages occurs in the same macroevolutionary rate regime. Correlations are mapped to a set of colors, with warmer colors corresponding to higher correlations than cooler colors. The set of colors is specified by the col argument and a legend is plotted to guide interpretation of the color-correlation map. Trees are plotted on the margins of the matrix image. The correlation between any two tips can be inferred by finding their intersection within the matrix image.

IMPORTANT: the legend DOES NOT apply to the phylorate plots shown in the margin if use.plot.bammdata=TRUE.

Examples

Run this code

data(whales, events.whales)
ed <- getEventData(whales, events.whales, burnin=0.1, nsamples=500)
x <- getCohortMatrix(ed)
cohorts(x, ed)
cohorts(x, ed, col='temperature')
cohorts(x, ed, ofs=0.05, col='temperature')
cohorts(x, ed, pal="temperature", col='temperature', use.plot.bammdata=TRUE)
# gray scale
cohorts(x, ed, col=gray(seq(0.2,0.9,length.out=128)),
        use.plot.bammdata=FALSE)