model.test.sim: Simulate Model Test
In TGuillerme/dispRity: Measuring Disparity

model.test.sim

R Documentation

Simulate Model Test

Description

Simulate models of disparity change through time

Usage

model.test.sim(
  sim = 1,
  model,
  model.rank = 1,
  alternative = "two-sided",
  time.split = NULL,
  time.span = 100,
  variance = 1,
  sample.size = 100,
  parameters = list(),
  fixed.optima = FALSE
)

Arguments

`sim`	The number of separate simulations to run.
`model`	Either (i) the named model of evolution to simulate for changes in disparity-through-time using a homogenous or hetergenous model (see list in `model.test`) or (ii) an object of class `dispRity` returned from `model.test` function. If a `dispRity` object is supplied, all remaining arguments apart from `sim` and `model.rank` and `alternative` are ignored as the model specified by the input model is used.
`model.rank`	If a `dispRity` object is supplied, which model is used for simulation. The rank refers to the order of models as specified by AICc, so if `model.rank = 1` (default) the best-fitting model is used for simulation.
`alternative`	If the simulation is based on a `dispRity` object, what is the alternative hypothesis: can be `"two-sided"` (default), `"greater"` or `"lesser"`.
`time.split`	The age of the change in mode. The age is measured as the time before the most recent sample, and multiple ages can be supplied in a vector. Note this only applies to heterogenous models.
`time.span`	The length of the sequence (`numeric`). If one number is supplied this is treated as the length of the sequence and the time span is treated as sequence from 0 to `time.span` in unit increments. If a vector of length > 1 is supplied, this is treated as the the age of each sample in the sequence.
`variance`	The variance of each sample (`numeric`). If one number is supplied this is the variance for all samples in the sequence. If a vector of equal length to the `time.span` vector is supplied, this is used for the variance of each sample in the sequence
`sample.size`	The sample size of each sample (`numeric`). If one number is supplied this is the sample size for all samples in the sequence. If a vector of equal length to the `time.span` vector is supplied, this is used for the sample size of each sample in the sequence
`parameters`	A `list` of model parameters used for simulations. See details.
`fixed.optima`	A `logical` value, whether to use an estimated optimum value in OU models (`FALSE` - default), or whether to set the OU optimum to the ancestral value (`TRUE`).

Details

DISCLAIMER: this function is working properly (i.e. it does what it is supposed to do), however, the interpretation of the results has not yet been thought through, discussed and peer-reviewed (what does a Brownian motion like disparity curve means biologically?).

The parameters is a list of arguments to be passed to the models. These arguments can be:

ancestral.state, ancestral value of the disparity applicable to all models (default = 0.01).
sigma.squared, rate of step variance to all models except Stasis (default = 1).
alpha, strength of attraction to the optimum in OU models (default = 1).
optima.1, the value of the optimum in a OU model, or the first bin optimum in a multi-OU model (default = 0.15).
optima.2, the second bin optimum in a multi-OU model (default = 0.15).
optima.3, the third bin optimum in a multi-OU model (default = 0.15).
theta.1, the mean in a Stasis model, or the first bin mean in a multi-Stasis model (default = 1).
theta.2, the second bin optimum in a multi-OU model (default = 1).
theta.3, the third bin optimum in a multi-OU model (default = 1).
omega, the variance in a Stasis model (default = 1).
trend, the trend parameter in the Trend model (default = 0.5).
eb.rate, the rate of exponential rate decrease in the EB model (default = -0.1).

Value

A list of class dispRity and model.sim. Each list element contains the simulated central tendency, as well as the variance, sample size, and subsets used to simulate the data.

Author(s)

Mark N Puttick and Thomas Guillerme

References

Blomberg SP, Garland T Jr, & Ives AR. 2003. Testing for phylogenetic signal in comparative data: behavioral traits are more labile. Evolution. 57, 717-745.

Hansen TF. 1997. Stabilizing selection and the comparative analysis of adaptation. Evolution. 51, 1341-1351.

Harmon LJ, et al. 2010. Early bursts of body size and shape evolution are rare in comparative data. 64, 2385-2396.

Hunt G. 2006. Fitting and comparing models of phyletic evolution: random walks and beyond. Paleobiology. 32, 578-601. DOI: 10.1666/05070.1.

Hunt G, Hopkins MJ & Lidgard S. 2015. Simple versus complex models of trait evolution and stasis as a response to environmental change. Proceedings of the National Academy of Sciences. 112, 4885-4890. DOI: 10.1073/pnas.1403662111

Felsenstein J. 1973. Maximum-likelihood estimation of evolutionary trees from continuous characters. American Journal of Human Genetics. 25, 471-492.

Felsenstein J. 1985. Phylogenies and the comparative method. The American Naturalist. 51, 1-15.

Murrell DJ. 2018. A global envelope test to detect non-random bursts of trait evolution. Methods in Ecology and Evolution. DOI: 10.1111/2041-210X.13006

Citation for the envelope code:

Examples

## Not run: 
## Disparity through time data
data(BeckLee_disparity)

## List of models to test
models <- list("Trend", "BM")

## Testing the models on the observed disparity
model_test_output <- model.test(BeckLee_disparity, models, time.split = 66)
 
## simulations using the output from model.test
model_test_sim_output <- model.test.sim(sim = 100, model= model_test_output)
 
## Plot the simulated best model
plot(model_test_sim_output)
## Add the observed data
plot(BeckLee_disparity, add = TRUE, col = c("pink", "#ff000050", "#ff000050"))

## Simulating a specific model with specific parameters parameters
model_simulation <- model.test.sim(sim = 100, model = "BM", time.span = 120, variance = 0.1,
                                   sample.size = 100, parameters = list(ancestral.state = 0,
                                   sigma.squared = 0.1))

## Summarising the results
plot(model_simulation, main = "A simple Brownian motion")

## End(Not run)

TGuillerme/dispRity documentation built on April 17, 2024, 10 p.m.