surfaceSimulate: 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 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

Value

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

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

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.