surfaceAICPlot: Plot the AIC Throughout a SURFACE Analysis
In surface: Fitting Hansen Models to Investigate Convergent Evolution

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

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

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

`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

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

Plots AIC values from a SURFACE analysis 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, surfaceTreePlot, surfaceTraitPlot

	## Not run: 
data(surfaceDemo)
tree<-surfaceDemo$tree
dat<-surfaceDemo$sim$dat
result<-runSurface(tree,dat)
surfaceAICPlot(result$fwd,result$bwd)
	
## End(Not run)