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
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
Once the package is loaded into your current working environment you
can call the package functions directly,
sim.fossils.poisson(). It is also possible to call
functions in R without loading the package into your working
Throughout this vignette and other documentation associated with
FossilSim, we call the
from the current working environment but use the
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.
relies on the widely used
object format for handling trees. The
phylo object stores
information about the relationship among branches in a phylogeny in a
edge and branch lengths are stored in a
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
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”.
paleotree vignette to see how
FossilSim objects can be converted into