surfaceSimulate {surface} | R Documentation |
Simulate Data for SURFACE
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 |
type |
Type of simulation desired - options are |
param |
If |
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 |
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 |
n_shifts |
Number of shifts to add to the Hansen model (if |
n_conv_shifts |
Number of convergent shifts to add to the Hansen model (if |
n_regimes |
Number of regimes to add to the Hansen model (if |
n_per_regime |
Integer vector of the number of shifts to each regime in the model (if |
no_nested |
A logical indicating whether to ensure that a pair of ‘convergent’ regimes is not in fact two nested clades (if |
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 |
optima_distrib |
Optional matrix of optima distribution for each trait (see |
optima_type |
How to sample optima based on |
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 |
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")))