surfaceTreePlot: Visualize Results of a SURFACE Analysis

Description

Plotting functions to visualize the results of a SURFACE analysis, with colors depicting regime structure: surfaceTreePlot produces a customized plot.phylo figure, and surfaceTraitPlot produces a scatterplot of trait values and optima

Usage

surfaceTreePlot(tree, hansenfit, cols = NULL, convcol = TRUE, labelshifts = FALSE, ...)
surfaceTraitPlot(dat, hansenfit, whattraits = c(1, 2), cols = NULL, 
convcol = TRUE, pchs = c(21, 21), cex.opt = 2.5, optellipses = FALSE, 
ellipsescale = 1, flatten1D = FALSE, add = FALSE, ypos = 0, plotoptima = TRUE, plottraits = TRUE, y.lim = NULL, x.lim = NULL, 
y.lab = NULL, x.lab = NULL, ...)

Arguments

tree

Phylogenetic tree in phylo format

dat

Trait data formatted as a data frame with named rows and at least two columns

hansenfit

An object containing the fitted Hansen model to use in plotting, with elements fit and savedshifts. This may be the list produced by any one iteration of surfaceForward or surfaceBackward, or the list produced by surfaceSimulate

whattraits

A two-element integer (or a single integer; see Details) indicating which traits to use for the (x,y) axes of a trait plot (defaults to c(1,2))

cols

An optional character vector of colors for painting branches in surfaceTreePlot or coloring symbols in surfaceTraitPlot. One color should be provided per regime in hansenfit; if cols=NULL the function will attempt an appropriate default

convcol

A logical indicating whether to select separate colors for convergent (colorful) and non-convergent (greyscale) regimes (defaults to TRUE)

labelshifts

A logical indicating whether to add integer labels to branches in the tree to show the order in which regime shifts were added in the forward phase (defaults to FALSE)

pchs

Vector with two integers representing the plotting characters to use for trait values and optima, respectively, in surfaceTraitPlot; both default to 21 (filled circles)

cex.opt

Character expansion for symbols representing the optima in surfaceTraitPlot; defaults to 2.5 (symbols representing data points can be specified with cex)

optellipses

A logical indicating whether to draw ellipses based on the fitted OU model instead of denoting optimum positions with pchs and cex.opt. The ellipses are drawn as the optima +/- the standard deviation of the stationary distribution of the inferred OU process: sigma_squared/(2*alpha), multiplied by ellipsescale

ellipsescale

A scalar or vector indicating how many standard deviations to draw ellipses above and below the optima; if a vector, concentric ellipses of various sizes will be drawn; defaults to 1

flatten1D

A logical indicating whether all regimes should be placed on a single line when surfaceTraitPlot is called for a single trait; defaults to FALSE

add

A logical indicating whether to add a new element to an existing surfaceTraitPlot graph instead of creating a new one; defaults to FALSE

ypos

Position on the y axis to place the traits and optima on; only applies if a single trait is used and flatten1D = TRUE

plotoptima

A logical indicating whether the optima should be displayed in surfaceTraitPlot; defaults to TRUE

plottraits

A logical indicating whether the trait values should be displayed in surfaceTraitPlot; defaults to TRUE

y.lim

Lower and upper limits for the y-axis; by default will be calculated to fit all points and ellipses fit in the frame

x.lim

Lower and upper limits for the x-axis; by default will be calculated to fit all points and ellipses fit in the frame

y.lab

y-axis label; defaults to the column name in the data frame

x.lab

x-axis label; defaults to the column name in the data frame

...

Additional arguments to be passed to the plot or points functions

Value

Creates one tree or trait plot on the current graphics device

Details

For trait plots using the option optellipses=TRUE, note that in some cases (e.g. if alpha is very small) the ellipses will not convey useful information. If trait data are unidimensional, or if whattraits is provided as a single integer, data will be plotted on the x-axis and the y-axis will separate different regimes (and ellipse width in the y-dimension will not be meaningful)

References

Ingram, T. & Mahler, D.L. (2013) SURFACE: detecting convergent evolution from comparative data by fitting Ornstein-Uhlenbeck models with stepwise AIC. Methods in Ecology and Evolution 4: 416-425.

Mahler, D.L., Ingram, T., Revell, L.J. & Losos, J.B. (2013) Exceptional convergence on the macroevolutionary landscape in island lizard radiations. Science 341: 292-295.