R: Simulate an Ornstein-Uhlenbeck model for continuous trait...

simulate_ou_model {castor} | R Documentation

## Simulate an Ornstein-Uhlenbeck model for continuous trait evolution.

### Description

Given a rooted phylogenetic tree and an Ornstein-Uhlenbeck (OU) model for the evolution of a continuous (numeric) trait, simulate random outcomes of the model on all nodes and/or tips of the tree. The function traverses nodes from root to tips and randomly assigns a state to each node or tip based on its parent's previously assigned state and the specified model parameters. The generated states have joint distributions consistent with the OU model. Optionally, multiple independent simulations can be performed using the same model.

### Usage

    simulate_ou_model(tree, stationary_mean, spread, decay_rate,
                      include_tips=TRUE, include_nodes=TRUE,
                      Nsimulations=1, drop_dims=TRUE)

### Arguments

`tree` | A rooted tree of class "phylo". The root is assumed to be the unique node with no incoming edge.
`stationary_mean` | Numeric. The mean (center) of the stationary distribution of the OU model.
`spread` | Numeric. The standard deviation of the stationary distribution of the OU model.
`decay_rate` | Numeric. Exponential decay rate (stabilization rate) of the OU model (in units 1/edge_length_units).
`include_tips` | Include random states for the tips. If `FALSE`, no states will be returned for tips.
`include_nodes` | Include random states for the nodes. If `FALSE`, no states will be returned for nodes.
`Nsimulations` | Number of random independent simulations to perform. For each node and/or tip, there will be `Nsimulations` random states generated.
`drop_dims` | Logical, specifying whether the returned `tip_states` and `node_states` (see below) should be vectors, if `Nsimulations==1`. If `drop_dims==FALSE`, then `tip_states` and `tip_nodes` will always be 2D matrices.

### Details

For each simulation, the state of the root is picked randomly from the stationary distribution of the OU model, i.e. from a normal distribution with mean = `stationary_mean` and standard deviation = `spread`.

If `tree$edge.length` is missing, each edge in the tree is assumed to have length 1. The tree may include multi-furcations (i.e. nodes with more than 2 children) as well as mono-furcations (i.e. nodes with only one child). The asymptotic time complexity of this function is O(Nedges*Nsimulations), where Nedges is the number of edges in the tree.

### Value

A list with the following elements:

`tip_states` | Either `NULL` (if `include_tips==FALSE`), or a 2D numeric matrix of size Nsimulations x Ntips, where Ntips is the number of tips in the tree. The [r,c]-th entry of this matrix will be the state of tip c generated by the r-th simulation. If `drop_dims==TRUE` and `Nsimulations==1`, then `tip_states` will be a vector.
`node_states` | Either `NULL` (if `include_nodes==FALSE`), or a 2D numeric matrix of size Nsimulations x Nnodes, where Nnodes is the number of nodes in the tree. The [r,c]-th entry of this matrix will be the state of node c generated by the r-th simulation. If `drop_dims==TRUE` and `Nsimulations==1`, then `node_states` will be a vector.

### Author(s)

Stilianos Louca

### See Also

`simulate_bm_model`, `simulate_mk_model`, `simulate_rou_model`

### Examples

    # generate a random tree
    tree = generate_random_tree(list(birth_rate_intercept=1),max_tips=10000)$tree

    # simulate evolution of a continuous trait
    tip_states = simulate_ou_model(tree, stationary_mean=10, spread=1, decay_rate=0.1)$tip_states

    # plot histogram of simulated tip states
    hist(tip_states, breaks=20, xlab="state", main="Trait probability distribution", prob=TRUE)

[Package castor version 1.7.2 Index]