surfaceAICPlot: Plot the AIC Throughout a SURFACE Analysis

Description

Plots a line graph showing how the AICc changed over the forward and backward phases of a SURFACE analysis. surfaceAICPlot can optionally show the change in the deviance or 'partial AICc' for each trait separately as well as for the analysis as a whole. surfaceAICMultiPlot plots lines from multiple runs on the same plot, allowing comparison among analyses done on alternate tree topologies or with stochasticity added using sample_shifts

Usage

surfaceAICPlot(fwd = NULL, bwd = NULL, out = NULL, summ = NULL, 
traitplot = "none", cols = NULL, daic = FALSE,  ...)
surfaceAICMultiPlot(fwd = NULL, bwd = NULL, out = NULL, summ = NULL, 
cols = NULL, daic = FALSE,  ...)

Arguments

fwd

List resulting from a surfaceForward run, or a list of such lists if calling surfaceAICMultiPlot

bwd

List resulting from a surfaceBackward run, or a list of such lists if calling surfaceAICMultiPlot

out

List resulting from a runSurface run, consisting of elements fwd and bwd, or a list of such lists if calling surfaceAICMultiPlot

summ

Object returned by surfaceSummary (run on the forward and backward phases of an analysis together), or a list of such objects if calling surfaceAICMultiPlot

traitplot

String indicating what values to use to draw lines corresponding to individual traits: "none", "dev" or "aic" (see details); defaults to "none"

cols

An optional character vector of colors for the AICc lines, used to color the different runs in surfaceAICMultiPlot. Only used in surfaceAICPlot if traitplot = "aic" or traitplot = "dev", in which case the colors are used for the trait lines (the overall AICc line is drawn in black)

daic

A logical indicating whether to rescale all delta-AICc (and delta-deviance) values to the value from the starting model; defaults to FALSE, but is automatically set to TRUE if traitplot = "aic" or traitplot = "dev"

...

Additional arguments to be passed to the plot or points functions

Value

Plots AIC values from a SURFACE analysis on the current graphics device

Details

If values are plotted on a trait-by-trait basis, either traitplot="dev" or traitplot="aic" can be specified. If traitplot="dev", the deviance (-2*log likelihood) at each step is shown for each trait. If traitplot="aic", a "partial AICc" at each step is shown for each of the m traits, consisting of the deviance and 1/m of the "penalty" part of the overall AICc, where m is the number of traits. Note that this is not a proper statistical construct, but its property of adding to give the overall AICc can be useful in visualizing the patterns among traits

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.