surfaceExtended: Interface between SURFACE and OUwie to fit complex multi-OU...
In mongiardino/extendedSurface: Fit Complex Multi-OU Models by Extending SURFACE and Providing an Interface with OUwie

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

View source: R/surfaceExtended.R

surfaceExtended uses the output of a SURFACE run to attempt to fit more complex Ornstein-Uhlenbeck models using OUwie. These models can incorporate differences between regimes in the rate of evolution (sigma^2), strength of attraction to trait optima (alpha), as well as optimize the state at the root of the tree (theta0). Optionally, the backwards phase of SURFACE is then extended by further merging regimes and attempting to use these simpler models as successive inputs to OUwie. Only one morphological trait can be employed. The function keeps track of successful instances of model fitting, and returns the models obtained through both SURFACE and OUwie, as well as an overall summary.

surfaceExtended(
  bwd_surface,
  data,
  tree,
  error = NA,
  models = c("OUMVA", "OUMVAZ"),
  limit = 2,
  plot = T,
  fwd_surface = NA
)

`bwd_surface`	List of models obtained using the backwards phase of SURFACE.
`data`	The morphological character under investigation. Needs to be the same data.frame used to run SURFACE.
`tree`	Phylogenetic tree in 'phylo' format. Needs to be the same used to run SURFACE.
`error`	Optional. Measurement errors to be incorporated in the process of model fitting. Can be a data.frame or vector, but it is assumed the order matches that of `data`.
`models`	Character vector specifying the models to be explored (see Details). Explores 'OUMVA' and 'OUMVAZ' models by default.
`limit`	Minimum number of regimes to explore. The default is 2.
`plot`	A logical indicating whether to plot the AICc of models output by SURFACE and OUwie. Default is `TRUE`.
`fwd_surface`	Optional. List of models obtained using the backwards phase of SURFACE. Only used to produce a more thorough comparison of models when `plot=TRUE`.

Paleontological data has been shown to improve the accuracy of models describing morphological evolution using OU models (Ho & Ané 2014). Nonetheless, many of the methods to fit multi-OU models that do not require users to specify the number and location of regime shifts work only on ultrametric trees. One that does not, SURFACE (Ingram & Mahler 2013), tends to favor overly complex models (Khabbazian et al. 2016), likely a consequence of assuming that regimes share a common sigma^2 and alpha parameters (Mongiardino Koch & Thompson 2020). Relaxing this assumption is not straightforward, as estimating these parameters for models with multiple regimes is often unfeasible (Benson et al. 2017).

surfaceExtended employs the optimal model found by the SURFACE algorithm and uses OUwie (Beaulieau et al. 2012) to attempt to fit multi-OU models in which rates of evolution and strengths of selection vary between regimes. The function then extends the backwards phase of SURFACE to merge independent regimes and find simpler multi-OU models. This is done in a stepwise fashion, and every time two regimes are merged, the result is used as input for OUwie.

The user can specify which parameters to estimate for each regime with OUwie, including different rates of evolution (models = 'OUMV'), different strengths of selection (models = 'OUMA'), or both (models = 'OUMVA'). The state at the root of the tree can be further considered an independent parameter by adding 'Z' at the end of the model's name (e.g., models = 'OUMAZ'), although this can destabilize parameter estimates (see OUwie for more details). Multiple models can be explored simultaneously by providing a vector with their names, or using models = 'all' or models = 'all_noZ'. In the latter, only models assuming the root value is distributed according to the stationary distribution of the ancestral OU process are optimized. The minimum number of regimes to be explored is determined by the limit parameter. By default, the results will be plotted using extended_surfaceAICPlot.

Can be very time-consuming depending on the size of the phylogeny and the complexity (number of regimes) of the starting model.

A list with the following elements:

$ext_surface: A list containing all the models explored by extending the backwards phase of SURFACE, identical to the one returned by surfaceBackward.
$summary: A data.frame including information on all the models explored using OUwie, including whether model fit was succesfull, and if so the AICc value.

Additionally, if model fit was successfull, the list will also include the best option found for each of the models specified with models. If multiple models were explored, the best option for each will be returned. For example, if OUMVA and OUMVAZ models were explored (as is the default), and model fitting was successful, the returned list will also contain two more elements, 'best_OUMVA' and 'best_OUMVAZ'. Note that these might differ in the number of regimes they contain.

Nicolás Mongiardino Koch

Beaulieu J.M., Jhuwueng D.‐C., Boettiger C., O'Meara B.C. 2012. Modeling stabilizing selection: expanding the Ornstein–Uhlenbeck model of adaptive evolution. Evolution, 66:2369–2383. Benson R.B.J., Hunt G., Carrano M.T., Campione N. (2018), Cope's rule and the adaptive landscape of dinosaur body size evolution. Palaeontology, 61:13-48. Ho L.S.T, Ané C. 2014. Intrinsic inference difficulties for trait evolution with Ornstein‐Uhlenbeck models. Methods in Ecology & Evolution, 5:1133–1146. Ingram T., Mahler D.L. 2013. SURFACE: detecting convergent evolution from comparative data by fitting Ornstein‐Uhlenbeck models with stepwise Akaike Information Criterion. Methods in Ecology & Evolution, 4:416–425. Khabbazian M., Kriebel R., Rohe K., Ané, C. 2016. Fast and accurate detection of evolutionary shifts in Ornstein‐Uhlenbeck models. Methods in Ecology & Evolution, 7:811–824. Mongiardino Koch N. 2021. Exploring adaptive landscapes across deep time: A case study using echinoid body size. Evolution, https://doi.org/10.1111/evo.14219.

For details on how these models are fit visit surfaceBackward and OUwie. Plots of AIC values can be obtained with extended_surfaceAICPlot

 ## Not run: 
  data(echinoid_data)
  OUmodels <- surfaceExtended(bwd_surface = echinoid_data$bwd_surface, data =
   echinoid_data$size, tree = echinoid_data$tree, error = echinoid_data$error,
   models = 'OUMVAZ', limit = 4, plot = T, fwd_surface =
   echinoid_data$fwd_surface)
 
## End(Not run)