This vignette provides a Quick start and a brief introduction to the package input and output.
FossilSim is an R package for simulating species taxonomy and fossil occurrence data in a phylogenetic framework. Simulations can be used to address many questions in phylogenetics and palaeobiology, and are especially useful for assessing the performance of different methods, since the true underlying parameters (e.g. diversification and fossil recovery rates) are known. Tara Smiley provides an excellent demonstration of the value of simulations in palaeobiology in this blog post.
FossilSim output can be easily parsed for downstream analysis using R, or other software packages including BEAST2 and RevBayes. The package provides a wide range of flexible models, including models of interval-, lineage- and environment-dependent fossil recovery, in addition to plotting functions that can be used to visualise the output and produce publication quality figures.
FossilSim is available on CRAN or the latest development version can be installed from GitHub using the package
# to install the package via CRAN install.packages("FossilSim") # to install the package via GitHub ::install_github("rachelwarnock/fossilsim") devtools # load the package into the current working environment library(FossilSim)
The installation above will automatically install the package dependencies,
Once the package is loaded into your current working environment you can call the package functions directly, e.g.
sim.fossils.poisson(). It is also possible to call functions in R without loading the package into your working environment, e.g.
FossilSim::sim.fossils.poisson(). Throughout this vignette and other documentation associated with
FossilSim, we call the
FossilSim functions from the current working environment but use the
:: format to call functions from other packages. This is done to make the source of all functions as clear as possible.
Simulating data using
FossilSim can be as simple as the following code snippets.
# simulate a tree using ape = 8 tips = ape::rtree(tips) t # simulate fossils using fossilsim = 2 rate = sim.fossils.poisson(rate = rate, tree = t) f # plot the output plot(f, tree = t)
# simulate taxonomy using fossilsim = 0.5 # probability of symmetric speciation beta = 0.1 # rate of anagenesis lambda.a = sim.taxonomy(tree = t, beta = beta, lambda.a = lambda.a) s # plot the output plot(s, tree = t, legend.position = "bottomright")
The package contains many options for simulating fossils and evaluating the output in a meaningful way requires understanding the underlying model parameters. Parsing the output for downstream analysis also requires becoming familiar with the
The starting point for any data generation using
FossilSim is a phylogenetic tree.
FossilSim relies on the widely used
phylo object format for handling trees. The
phylo object stores information about the relationship among branches in a phylogeny in a matrix called
edge and branch lengths are stored in a vector called
edge.length. The age of the tips and internal nodes can be reconstructed by combining information from the
edge matrix and the
edge.length vector. If the tree has a root edge (i.e. a branch leading to the root) the length of this edge is stored as a numeric variable called
There are a huge number of packages and options for simulating trees that can be used as input in
FossilSim, including the
TreeSim R packages. An empirical phylogeny can also be used as input. The only general requirements are that trees are fully resolved and scaled to time.
FossilSim can be used to simulate species taxonomy and fossil sampling times, which are stored and output as the
fossils objects described in the “Simulating taxonomy” and “Simulating fossils” vignettes. The functions used to simulate fossils can take either a
taxonomy object as input. This means, in theory, the user never has to interact with the
taxonomy object when simulating fossil data. However, it may still be useful to become familiar with the concepts underlying the
Information about the
taxonomy object and models for simulating taxonomy can be found in the vignette “Simulating taxonomy”. Information about the
fossils object and models for simulating fossils can be found in the vignette “Simulating fossils”. See the
paleotree vignette to see how
FossilSim objects can be converted into