ouSim: Discrete-time simulation of Ornstein-Uhlenbeck models on a...
In maticce: Mapping Transitions in Continuous Character Evolution

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

ouSim simulates the evolution of a single character for visualization purposes; for parametric bootstrapping, utilize the simulate methods in ouch.

  ouSim(object, ...)
  ## S3 method for class 'phylo'
ouSim(object, rootState = 0, shiftBranches = NULL, shiftStates = NULL, 
                        sqrt.alpha = 0, variance = 1, theta = rootState, model = "OU", 
						branchMeans = NULL, steps = 1000, ...)
  ## S3 method for class 'ouchtree'
ouSim(object, rootState = 0, sqrt.alpha = 0, variance = 1, 
                           theta = rootState, steps = 1000, ...)
  ## S3 method for class 'browntree'
ouSim(object, ...)
  ## S3 method for class 'hansentree'
ouSim(object, ...)
  ## S3 method for class 'hansenBatch'
ouSim(object, ...)
  ## S3 method for class 'hansenSummary'
ouSim(object, tree, treeNum = 1, rootState = NULL, ...)

`object`	In a call to the generic function, an object of class phylo, ouchtree, browntree, hansentree, hansenBatch, or hansenSummary.
`rootState`	The character state at the root of the tree. In a `browntree` object, this value is provided. In a `hansentree` or `batchHansen` object, the value at the root is not provided, but it is taken to be the equilibrium or optimum (`theta`) at the root of the tree.
`shiftBranches`	For a `phylo` tree only. An optional vector indicating any branches at which an OU model has a determined shift in ancestral state. Same order as `shiftStates`. This argument and `shiftStates` are only needed if you want to specify a model with a disjunction in phenotype, similar to restarting evolution at a new point.
`shiftStates`	For a `phylo` tree only. An optional vector of length = `length(shiftStates)` indicating the ancestral states for the branches at which the state shifts.
`sqrt.alpha`	The rate of evolution toward an equilibrium or optimum. This term is refered to as the rate of evolution by Hansen (1997) and the strength of selection by Butler and King (2004). It is a multiplier by the difference between the character state and the character state optimum. Alpha can be submitted as a single value applied to all branches or as a vector corresponding to branches in the `phylo` object. At `sqrt.alpha = 0`, the simulation approximates a Brownian motion process. This parameter is taken from the analysis results for `browntree` (`sqrt.alpha` = 0), `hansentree` (point estimate), `hansenBatch` or `hansenSummary` (model-averaged).
`variance`	The variance on the stochastic portion of the Ornstein-Uhlenbeck model. This parameter is taken from the analysis results for `browntree` (`alpha` = 0), `hansentree` (point estimate), `hansenBatch` or `hansenSummary` (model-averaged).
`theta`	The character state optimum. `theta` can be submitted as a single value or, like `alpha`, as a vector corresponding to branches of the tree. This parameter is taken from the analysis results for `browntree` (`alpha` = 0), `hansentree` (point estimate), `hansenBatch` or `hansenSummary` (model-averaged).
`model`	For a `phylo` tree only. Specify "OU" for Ornstein-Uhlenbeck and Brownian motion models, "meanVar" for a model in which the variance is constant across the tree, but mean varies by branch, and distribution in each generation depends on only these parameters (ancestry is not considered, only current mean and variance).
`branchMeans`	For a `phylo` tree only. The mean for each branch, utilized only in the “meanVar” model.
`steps`	The number of slices into which the tree is divided for simulation.
`tree`	The `ouch`-style tree to simulate on.
`treeNum`	In a `hansenBatch` or `hansenSummary` object, the number of the tree from which analysis parameters should be drawn; should match the tree provided with `tree`.
`...`	Additional arguments to be passed along to `ouSim`.

A call to ouSim detects the class of object and behaves as follows:

phylo With an ape-style tree, all parameters of the model are specified by branch. Most flexibility, least convenience.
ouchtree With an ouch-style (S4) tree, again, all parameters of the model are specified by branch. Somewhat less flexibility than ouSim.phylo but all the pain. Typically just called by the next two methods.
browntree All Brownian motion model parameters and tree are extracted from the browntree object.
hansentree All Ornstein-Uhlenbeck model parameters and tree are extracted from the hansentree object. Only the first regime is utilized.
hansenBatch Model-averaged parameters from the hansenBatch object are used for analysis. One of the trees used for analysis must be provided, and a corresponding tree number must be provided so that branches are indexed correctly.
hansenSummary Behaves exactly like a hansenBatch object.
ouSim.phylo A very basic simulation engine, but also the most flexible. As written, the user has to specify the model using two vectors that correspond to the branches in an ape-format tree. It is important to note that this simulation method is really a heuristic device, not appropriate for estimating parameter distributions. For analysis purposes, you should utilize the simulate and bootstrap methods in ouch.