generate_random_tree {castor}  R Documentation 
Generate a random timetree via simulation of a Poissonian speciation/extinction (birth/death) process. New species are added (born) by splitting of a randomly chosen extant tip. The treewide birth and death rates of tips can each be constant or powerlaw functions of the number of extant tips. For example,
B = I + F\cdot N^E,
where B is the treewide birth rate (species generation rate), I is the intercept, F is the powerlaw factor, N is the current number of extant tips and E is the powerlaw exponent. Optionally, the percapita (tipspecific) birth and death rates can be extended by adding a custom time series provided by the user.
generate_random_tree(parameters = list(), max_tips = NULL, max_extant_tips = NULL, max_time = NULL, max_time_eq = NULL, coalescent = TRUE, as_generations = FALSE, no_full_extinction = TRUE, Nsplits = 2, added_rates_times = NULL, added_birth_rates_pc = NULL, added_death_rates_pc = NULL, added_periodic = FALSE, tip_basename = "", node_basename = NULL, edge_basename = NULL, include_birth_times = FALSE, include_death_times = FALSE)
parameters 
A named list specifying the birthdeath model parameters, with one or more of the following entries:

max_tips 
Integer, maximum number of tips of the tree to be generated. If 
max_extant_tips 
Integer, maximum number of extant lineages allowed at any moment during the simulation. If this number is reached, the simulation is halted. If 
max_time 
Numeric, maximum duration of the simulation. If 
max_time_eq 
Maximum duration of the simulation, counting from the first point at which speciation/extinction equilibrium is reached, i.e. when (birth rate  death rate) changed sign for the first time. If 
coalescent 
Logical, specifying whether only the coalescent tree (i.e. the tree spanning the extant tips) should be returned. If 
as_generations 
Logical, specifying whether edge lengths should correspond to generations. If FALSE, then edge lengths correspond to time. 
no_full_extinction 
Logical, specifying whether to prevent complete extinction of the tree. Full extinction is prevented by temporarily disabling extinctions whenever the number of extant tips is 1. Note that, strictly speaking, the trees generated do not exactly follow the proper probability distribution when 
Nsplits 
Integer greater than 1. Number of childtips to generate at each diversification event. If set to 2, the generated tree will be bifurcating. If >2, the tree will be multifurcating. 
added_rates_times 
Numeric vector, listing time points (in ascending order) for the custom percapita birth and/or death rates time series (see 
added_birth_rates_pc 
Numeric vector of the same size as 
added_death_rates_pc 
Numeric vector of the same size as 
added_periodic 
Logical, indicating whether 
tip_basename 
Character. Prefix to be used for tip labels (e.g. "tip."). If empty (""), then tip labels will be integers "1", "2" and so on. 
node_basename 
Character. Prefix to be used for node labels (e.g. "node."). If 
edge_basename 
Character. Prefix to be used for edge labels (e.g. "edge."). Edge labels (if included) are stored in the character vector 
include_birth_times 
Logical. If 
include_death_times 
Logical. If 
If max_time==NULL
, then the returned tree will always contain max_tips
tips. In particular, if at any moment during the simulation the tree only includes a single extant tip, the death rate is temporarily set to zero to prevent the complete extinction of the tree. If max_tips==NULL
, then the simulation is ran as long as specified by max_time
. If neither max_time
nor max_tips
is NULL
, then the simulation halts as soon as the time exceeds max_time
or the number of tips (extant tips if coalescent
is TRUE
) exceeds max_tips
. If max_tips!=NULL
and Nsplits>2
, then the last diversification even may generate fewer than Nsplits
children, in order to keep the total number of tips within the specified limit.
If rarefaction<1
and resolution>0
, collapsing of closely related tips (at the resolution specified) takes place prior to rarefaction (i.e., subsampling applies to the already collapsed tips).
Both the percapita birth and death rates can be made into completely arbitrary functions of time, by setting all powerlaw coefficients to zero and providing custom time series added_birth_rates_pc
and added_death_rates_pc
.
A named list with the following elements:
success 
Logical, indicating whether the tree was successfully generated. If 
tree 
A rooted bifurcating (if 
root_time 
Numeric, giving the time at which the tree's root was first split during the simulation. Note that if 
final_time 
Numeric, giving the final time at the end of the simulation. Note that if 
root_age 
Numeric, giving the age (time before present) at the tree's root. This is equal to 
equilibrium_time 
Numeric, giving the first time where the sign of (death rate  birth rate) changed from the beginning of the simulation, i.e. when speciation/extinction equilibrium was reached. May be infinite if the simulation stoped before reaching this point. 
extant_tips 
Integer vector, listing indices of extant tips in the tree. If 
Nbirths 
Total number of birth events (speciations) that occurred during tree growth. This may be lower than the total number of tips in the tree if death rates were nonzero and 
Ndeaths 
Total number of deaths (extinctions) that occurred during tree growth. 
Ncollapsed 
Number of tips removed from the tree while collapsing at the resolution specified. 
Nrarefied 
Number of tips removed from the tree due to rarefaction. 
birth_times 
Numeric vector, listing the times of speciation events during tree growth, in order of occurrence. Note that if 
death_times 
Numeric vector, listing the times of extinction events during tree growth, in order of occurrence. Note that if 
error 
Character, containing an explanation of ther error that occurred. Only included if 
Stilianos Louca
D. J. Aldous (2001). Stochastic models and descriptive statistics for phylogenetic trees, from Yule to today. Statistical Science. 16:2334.
M. Steel and A. McKenzie (2001). Properties of phylogenetic trees generated by Yuletype speciation models. Mathematical Biosciences. 170:91112.
# Simple speciation model parameters = list(birth_rate_intercept=1) tree = generate_random_tree(parameters,max_tips=100)$tree # Exponential growth rate model parameters = list(birth_rate_factor=1) tree = generate_random_tree(parameters,max_tips=100)$tree