secsse_sim: Function to simulate a tree, conditional on observing all...

View source: R/secsse_sim.R

secsse_simR Documentation

Function to simulate a tree, conditional on observing all states.

Description

By default, secsse_sim assumes CLA-secsse simulation, e.g. inheritance of traits at speciation need not be symmetrical, and can be specified through usage of lambda-matrices. Hence, the input for lambdas is typically a list of matrices.

Simulation is performed with a randomly sampled initial trait at the crown - if you, however - want a specific, single, trait used at the crown, you can reduce the possible traits by modifying pool_init_states.

By default, the algorithm keeps simulating until it generates a tree where both crown lineages survive to the present - this is to ensure that the tree has a crown age that matches the used crown age. You can modify 'non-extinction' to deviate from this behaviour.

Usage

secsse_sim(
  lambdas,
  mus,
  qs,
  crown_age,
  num_concealed_states,
  pool_init_states = NULL,
  max_spec = 1e+05,
  min_spec = 2,
  max_species_extant = TRUE,
  tree_size_hist = FALSE,
  conditioning = "obs_states",
  non_extinction = TRUE,
  verbose = FALSE,
  max_tries = 1e+06,
  drop_extinct = TRUE,
  start_at_crown = TRUE,
  seed = NULL
)

Arguments

lambdas

speciation rates, in the form of a list of matrices.

mus

extinction rates, in the form of a vector.

qs

The Q matrix, for example the result of function q_doubletrans, but generally in the form of a matrix.

crown_age

crown age of the tree, tree will be simulated conditional on non-extinction and this crown age.

num_concealed_states

number of concealed states, generally equivalent to the number of examined states in the dataset.

pool_init_states

pool of initial states at the crown, in case this is different from all available states, otherwise leave at NULL

max_spec

Maximum number of species in the tree (please note that the tree is not conditioned on this number, but that this is a safeguard against generating extremely large trees).

min_spec

Minimum number of species in the tree.

max_species_extant

Should the maximum number of species be counted in the reconstructed tree (if TRUE) or in the complete tree (if FALSE).

tree_size_hist

if TRUE, returns a vector of all found tree sizes.

conditioning

can be "obs_states", "true_states" or "none", the tree is simulated until one is generated that contains all observed states ("obs_states"), all true states (e.g. all combinations of obs and hidden states), or is always returned ("none"). Alternatively, a vector with the names of required observed states can be provided, e.g. c("S", "N").

non_extinction

boolean stating if the tree should be conditioned on non-extinction of the crown lineages. Defaults to TRUE.

verbose

sets verbose output; default is TRUE when optimmethod is "simplex". If optimmethod is set to "simplex", then even if set to FALSE, optimizer output will be shown.

max_tries

maximum number of simulations to try to obtain a tree.

drop_extinct

boolean stating if extinct species should be dropped from the tree. Defaults to TRUE.

start_at_crown

if FALSE, the simulation starts with one species instead of the two assumed by default by secsse (also in ML), and the resulting crown age will be lower than the set crown age. This allows for direct comparison with BiSSE and facilitates implementing speciation effects at the crown.

seed

pseudo-random number generator seed.

Value

a list with four properties: phy: reconstructed phylogeny, true_traits: the true traits in order of tip label, obs_traits: observed traits, ignoring hidden traits and lastly: initialState, delineating the initial state at the root used.


secsse documentation built on June 22, 2024, 11:35 a.m.