runSurface: Run All Steps of a SURFACE Analysis

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

View source: R/runSurface.R


Carries out both the forward and backward phases of SURFACE's stepwise AIC routine, with sensible default behaviors.


runSurface(tree, dat, exclude = 0, aic_threshold = 0, max_steps = NULL, 
verbose = FALSE, plotaic = FALSE, error_skip = FALSE, only_best = FALSE,
sample_shifts=FALSE, sample_threshold = 2)



Phylogenetic tree in phylo format


Data frame with taxa names as rownames matching the tip labels of tree, and one or more columns of trait data


Optionally, the proportion of the worst models (AICc scores for each shift point) to exclude in the current round of the forward phase (defaults to zero)


Change in AICc needed to accept a candidate model as a sufficient improvement over the previous iteration of SURFACE. Defaults to zero, meaning any improvement in the AICc will be accepted; more stringent thresholds are specified using *negative* values of aic_threshold


Maximum number of steps to allow to allow each phase to carry out (assuming the model improvement continues to exceed aic_threshold)


A logical indicating whether to print progress (defaults to FALSE)


A logical indicating whether to plot AICc values of all candidate models at each step (defaults to FALSE)


A logical indicating whether to only allow one pair of regimes to be collapsed at each iteration; if FALSE, igraph functions are used to identify pairs of regimes that can be collapsed to improve the model without any inconsistencies (defaults to FALSE)


A logical indicating whether to skip over any candidate model that produces an error message during likelihood optimization (this is rare, but can cause an entire analysis to abort; defaults to FALSE)


A logical indicating whether to randomly sample from among the best models at each step (those within sample_threshold of the best AICc), rather than deterministically selecting the best candidate model (defaults to FALSE)


Number of AICc units within which to sample among candidate models that are close to as good as the best model at each step (defaults to 2, but only used if sample_shifts=TRUE, and only used in the backward phase if only_best=TRUE)


Carries out all steps of SURFACE, including converting data structures and running both forward and backward phases of the analysis. The default behavior should be appropriate in most circumstances, but some functionalities require using the functions surfaceForward and surfaceBackward that are called by runSurface


A list with two elements, fwd and bwd.


The results of the forward phase, as returned by surfaceForward


The results of the backward phase, as returned by surfaceBackward


Travis Ingram


Butler, M.A. & King, A.A. (2004) Phylogenetic comparative analysis: a modeling approach for adaptive evolution. American Naturalist 164: 683-695.

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.

See Also

surfaceBackward, surfaceForward

surface documentation built on May 30, 2017, 1:58 a.m.