paleobuddy

paleobuddy is an R package to simulate species diversification, fossil records, and phylogenetic trees. While the literature on species birth-death simulators is extensive, including important software like paleotree and APE, we concluded there were interesting gaps to be filled regarding possible diversification scenarios. Differently from most simulators in the field, we strove for flexibility over focus, implementing a large array of regimens for users to experiment with and combine, and structuring the package on a general framework to allow for straightforward expansion of available scenarios. In this way, paleobuddy can be used as a complement to other simulators or, in the case of scenarios implemented only here, can allow for robust and easy simulations for novel scenarios.

Installation

You can install the released version of paleobuddy from CRAN with:

install.packages("paleobuddy")

And the development version from GitHub with:

library(devtools)
devtools::install_github("brpetrucci/paleobuddy")

Example

We run a simple birth-death simulation as follows

set.seed(1)

n0 <- 1 # initial number of species
lambda <- 0.1 # speciation rate
mu <- 0.05 # extinction rate
tMax <- 30 # maximum simulation time

# run simulation
sim <- bd.sim(n0, lambda, mu, tMax)

We can then generate fossil records, and visualize the results

set.seed(1)

rho <- 1 # sampling rate
bins <- seq(tMax, 0, -1) # something to simulate geologic intervals

# get a data frame with fossil occurrence times
fossils <- sample.clade(sim = sim, rho = rho, tMax = tMax, bins = bins)

# visualize simulation and fossil occurrences
draw.sim(sim, fossils)

And generate phylogenies as well

phy <- make.phylo(sim) # make a phylogenetic tree with the simulated group
ape::plot.phylo(phy, root.edge = TRUE) # plot it with a stem (requires APE)
ape::axisPhylo() # add axis

Important functions

bd.sim is the birth-death simulation function, allowing for multiple arguments to build a large number of possible scenarios. One can supply constant or time-dependent speciation rate lambda and extinction rate mu. On top of the base rates, we allow for a shape parameter for each, if one chooses to interpret lambda and mu as scales of a Weibull distribution for age-dependent diversification. We take the novel step allowing for time-dependent scale and shape as well. One can also supply an env parameter to make rates dependent on a time-series, such as temperature. These can all be combined as the user wishes, creating a myriad of possible scenarios.

sample.clade generates fossil records, returning an organized data frame with occurrence times - or occurrence time ranges, provided the user supplies the respective interval vector. It allows for a sampling rate rho that can be as flexible as lambda and mu above, with the exception of a shape parameter, since we omitted that option given the absence of the use of Weibull distributions to model age-dependent fossil sampling in the literature. Instead, we allow for the user to supply a function they wish to use as age-dependent sampling, adFun, such as the PERT distribution used in PyRate.

make.phylo closes the trio of most important functions of the package, taking a paleobuddy simulation and returning a phylo object from the APE package (see above).

draw.sim allows for easy visualization of birth-death simulation objects, drawing species’ durations and kinship, besides allowing for the addition of fossil occurrences as well.

Besides its main simulating and visualization functions, paleobuddy also supplies the user with a few interesting statistical tools, such as rexp.var, a generalization of the rexp function in base R that allows for time-varying exponential rates and a shape parameter, in which case it generalizes the rweibull function.

Data

Given the possibility of functions in paleobuddy to use environmentally-dependent rates, we have included with the package data frames containing environmental data, namely temperature (temp) and co2 (co2). These have been modified from data on RPANDA (RPANDA: Morlon H. et al (2016) RPANDA: an R package for macroevolutionary analyses on phylogenetic trees. Methods in Ecology and Evolution 7: 589-597). To see more about the origin of the data, see ?data, where data is the data frame’s name.

Authors

paleobuddy was idealized by Bruno do Rosario Petrucci and Tiago Bosisio Quental. The birth-death, statistical, and part of the sampling functions were written by Bruno. The phylogeny and most of the sampling functions were written by Matheus Januário.