surfaceTreePlot: Visualize Results of a SURFACE Analysis
In surface: Fitting Hansen Models to Investigate Convergent Evolution

Description Usage Arguments Details Value Author(s) References See Also Examples

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

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, ...)

`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

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)

Creates one tree or trait plot on the current graphics device

Travis Ingram

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.

surfaceForward, surfaceBackward, surfaceSimulate, surfaceSummary, surfaceAICPlot

data(surfaceDemo)
tree<-surfaceDemo$tree
dat<-surfaceDemo$sim$dat
olist<-convertTreeData(tree,dat)
otree<-olist[[1]]; odata<-olist[[2]]
startmod<-startingModel(otree, odata, shifts = c("6"="b")) 
surfaceTreePlot(tree,startmod[[1]],labelshifts=TRUE,cols=c("black","red"))
surfaceTraitPlot(dat,startmod[[1]],whattraits=c(1,2),cols=c("black","red"))