secsse_sim: 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,
  seed = NULL
)

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.

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.
seed: pseudo-random number generator seed.