surfaceSimulate: Simulate Data for SURFACE

In surface: Fitting Hansen Models to Investigate Convergent Evolution

Description

Provides several ways to simulate data sets on phylogenetic trees in conjunction with SURFACE analyses. Can simulate under simple models without regime shifts, under a Hansen model with sampled shift locations, or under a fitted Hansen model (optionally with resampled optima)

Usage

surfaceSimulate(phy, type = "BM", param = 0, n_traits = NULL, dat = NULL, 
vcv = NULL, hansenfit = NULL, shifts = NULL, n_shifts = NULL, 
n_conv_shifts = NULL, n_regimes = NULL, n_per_regime = NULL, 
no_nested = TRUE, optima = NULL, sample_optima = TRUE, 
optima_distrib = NULL, optima_type = "rnorm", sigma_squared = NULL, 
alpha = NULL, pshift_timefactor = NULL)

Arguments

phy	A phylogenetic tree in phylo format on which to simulate data
type	Type of simulation desired - options are "BM", "hansen-fit", and "hansen-paint" (see Details)
param	If type="BM", an optional parameter to rescale the tree (see Details)
n_traits	Number of traits (if not provided will be determined from other inputs or default to 1)
dat	Optional data frame of original trait data (function will use this to extract features of the data set)
vcv	Optional evolutionary variance-covariance matrix
hansenfit	A fitted Hansen model (or a list of such if multiple traits) (if type = "hansen-fit")
shifts	A vector of regime shifts, named for the branches they are to be placed on in the Hansen model to be simulated under (if type = "hansen-paint"). If specified, n_shifts, n_conv_shifts, n_regimes and n_per_regime are all ignored
n_shifts	Number of shifts to add to the Hansen model (if type = "hansen-paint")
n_conv_shifts	Number of convergent shifts to add to the Hansen model (if type = "hansen-paint"). Either n_conv_shifts or n_regimes can be specified along with n_shifts, but not both
n_regimes	Number of regimes to add to the Hansen model (if type = "hansen-paint"). Either n_conv_shifts or n_regimes can be specified along with n_shifts, but not both
n_per_regime	Integer vector of the number of shifts to each regime in the model (if type = "hansen-paint"). If specified, the vector length determines n_regimes, and the sum of the values determines n_shifts, and the number of entries >1 determines n_conv_shifts
no_nested	A logical indicating whether to ensure that a pair of ‘convergent’ regimes is not in fact two nested clades (if type = "hansen-paint"; defaults to TRUE)
optima	Optional matrix of optima
sample_optima	A logical indicating whether to replace the optima in the fitted model with new values from a distribution based on the inferred optima (if type = "hansen-fit"; defaults to TRUE)
optima_distrib	Optional matrix of optima distribution for each trait (see optima_type). Each column is a two-element vector c(A, B) for the trait.
optima_type	How to sample optima based on optima_distrib. Can be one of "rnorm" (default; distribution is normal with mean=A, sd=B), "runif" (distribution is uniform with center=A, width=B), or "even" (optima are evenly spaced with spacing=B, then randomized)
sigma_squared	Scalar or vector of Brownian rate parameters to use in simulations
alpha	Scalar or vector of OU attraction parameter values to use in simulations
pshift_timefactor	Factor by which to bias sampling of branches to place regimes on to be earlier (if <1) or later (if >1) in the tree. The sampling probability will be pshift_timefactor times higher at the tips than at the root

Details

Type of simulation may be "BM", "hansen-fit", or "hansen-paint".

If type = "BM", simulation uses the sim.char function in geiger, with Brownian rate sigma_squared. If type = "BM", param values other than 0 will transform the tree based on the Early Burst (param < 0) or single-peak Ornstein-Uhlenbeck (param > 0) model before simulating, causing trait disparity to be concentrated earlier or later in the tree, respectively

If type = "hansen-fit", an existing hansentree object is used as the basis of simulation using ouch functions, optionally with new parameter values

If type = "hansen-paint", a new hansentree object is produced for simulation using ouch functions, with specified parameter values and numbers of regimes and/or regime shifts

Value

A list with the following components (most are NULL if type = "BM"):

data	Simulated trait data in a data frame
optima	Matrix of optima for each regime for each trait in the generating model
savedshifts	Shift locations in the generating Hansen model
regimes	Regime assignments of tip taxa
shifttimes	Timing of each shift in the Hansen model (measured from the root of the tree
fit	Generating Hansen model used in the simulation

Author(s)

Travis Ingram

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.

See Also

surfaceForward, surfaceBackward, surfaceTreePlot, surfaceTraitPlot

Examples

data(surfaceDemo)
tree<-surfaceDemo$tree
dat<-surfaceDemo$sim$dat
olist<-convertTreeData(tree,dat)
otree<-olist[[1]]; odata<-olist[[2]]
sim<-surfaceSimulate(otree,type="hansen-paint",dat=dat,shifts=c(c("1"="a","6"="b","17"="c")))

surface documentation built on Dec. 18, 2020, 5:08 p.m.