The FossilSim package
In FossilSim: Simulation and Plots for Fossil and Taxonomy Data

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 5, fig.height = 5
)

This vignette provides a [Quick start] and a brief introduction to the package input and output.

[Background and motivation]
[Installing the package]
[Quick start]
[FossilSim input]
[FossilSim output]
[What next?]

Background and motivation

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.

Installing the package

FossilSim is available on CRAN or the latest development version can be installed from GitHub using the package devtools.

# to install the package via CRAN
install.packages("FossilSim")

# to install the package via GitHub
devtools::install_github("rachelwarnock/fossilsim")

# load the package into the current working environment
library(FossilSim)

library(FossilSim)

Package dependencies

The installation above will automatically install the package dependencies, ape and TreeSim.

Calling functions from FossilSim and other packages

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.

Quick start

Simulating data using FossilSim can be as simple as the following code snippets.

set.seed(121)

# simulate a tree using ape
tips = 8
t = ape::rtree(tips)
# simulate fossils using fossilsim
rate = 2
f = sim.fossils.poisson(rate = rate, tree = t)  
# plot the output
plot(f, tree = t)

# simulate taxonomy using fossilsim
beta = 0.5 # probability of symmetric speciation
lambda.a = 0.1  # rate of anagenesis
s = sim.taxonomy(tree = t, beta = beta, lambda.a = lambda.a)  
# 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 FossilSim objects.

FossilSim input

The starting point for any data generation using FossilSim is a phylogenetic tree. FossilSim relies on the widely used ape package 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 root.edge.

There are a huge number of packages and options for simulating trees that can be used as input in FossilSim, including the ape and 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 output

FossilSim can be used to simulate species taxonomy and fossil sampling times, which are stored and output as the taxonomy and fossils objects described in the "Simulating taxonomy" and "Simulating fossils" vignettes. The functions used to simulate fossils can take either a phylo or 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 taxonomy object.

What next?

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 paleotree objects.