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

In rsetienne/secsse: Several Examined and Concealed States-Dependent Speciation and Extinction

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.

rsetienne/secsse documentation built on April 29, 2024, 11:52 p.m.