plot.fossils {FossilSim}

Plot simulated fossils

Description

This function is adapted from the ape function plot.phylo used to plot phylogenetic trees. The function can be used to plot simulated fossils (show.fossils = TRUE), with or without the corresponding tree (show.tree = TRUE), stratigraphic intervals (show.strata = TRUE), stratigraphic ranges (show.ranges = TRUE) and sampling proxy data (show.proxy = TRUE). Interval ages can be specified as a vector (interval.ages) or a uniform set of interval ages can be specified using the number of intervals (strata) and maximum interval age (max), where interval length = max.age/strata. If no maximum age is specified, the function calculates a maximum interval age slightly older than the root edge (or root age if root.edge = FALSE), using the function tree.max().

Usage

## S3 method for class 'fossils'
plot(
  x,
  tree,
  show.fossils = TRUE,
  show.tree = TRUE,
  show.ranges = FALSE,
  show.strata = FALSE,
  strata = 1,
  max.age = NULL,
  interval.ages = NULL,
  binned = FALSE,
  show.axis = TRUE,
  show.proxy = FALSE,
  proxy.data = NULL,
  show.preferred.environ = FALSE,
  preferred.environ = NULL,
  show.taxonomy = FALSE,
  taxonomy = NULL,
  show.unknown = FALSE,
  rho = 1,
  root.edge = TRUE,
  hide.edge = FALSE,
  edge.width = 1,
  show.tip.label = FALSE,
  align.tip.label = FALSE,
  reconstructed = FALSE,
  fossil.col = 1,
  range.col = rgb(0, 0, 1),
  extant.col = 1,
  taxa.palette = "viridis",
  col.axis = "gray35",
  cex = 1.2,
  pch = 18,
  ...
)

Arguments

x

Fossils object.

tree

Phylo object.

show.fossils

If TRUE plot fossils (default = TRUE).

show.tree

If TRUE plot the tree (default = TRUE).

show.ranges

If TRUE plot stratigraphic ranges (default = FALSE). If show.taxonomy = FALSE all occurrences along a single edge are grouped together (i.e. function assumes all speciation is symmetric).

show.strata

If TRUE plot strata (default = FALSE).

strata

Number of stratigraphic intervals (default = 1).

max.age

Maximum age of a set of equal length intervals. If no value is specified (max = NULL), the function uses a maximum age based on tree height.

interval.ages

Vector of stratigraphic interval ages, starting with the minimum age of the youngest interval and ending with the maximum age of the oldest interval.

binned

If TRUE fossils are plotted at the mid point of each interval.

show.axis

If TRUE plot x-axis (default = TRUE).

show.proxy

If TRUE add profile of sampling data to plot (e.g. rates in time-dependent rates model) (default = FALSE).

proxy.data

Vector of sampling proxy data (default = NULL). Should be as long as the number of stratigraphic intervals.

show.preferred.environ

If TRUE add species preferred environmental value (e.g. water depth) (default = FALSE). Only works if combined with show.proxy = TRUE.

preferred.environ

Preferred environmental value (e.g. water depth). Currently only one value can be shown.

show.taxonomy

If TRUE highlight species taxonomy.

taxonomy

Taxonomy object.

show.unknown

If TRUE plot fossils with unknown taxonomic affiliation (i.e. sp = NA) (default = FALSE).

rho

Extant species sampling probability (default = 1). Will be disregarded if fossils object already contains extant samples.

root.edge

If TRUE include the root edge (default = TRUE).

hide.edge

If TRUE hide the root edge but still incorporate it into the automatic timescale (default = FALSE).

edge.width

A numeric vector giving the width of the branches of the plotted phylogeny. These are taken to be in the same order as the component edge of tree. If fewer widths are given than the number of edges, then the values are recycled.

show.tip.label

Whether to show the tip labels on the phylogeny (defaults to FALSE).

align.tip.label

A logical value or an integer. If TRUE, the tips are aligned and dotted lines are drawn between the tips of the tree and the labels. If an integer, the tips are aligned and this gives the type of the lines (following lty).

reconstructed

If TRUE plot the reconstructed tree. If fossils object contains no extant samples, the function assumes rho = 1 and includes all species at the present.

fossil.col

Colour of fossil occurrences. A vector equal to the length of the fossils object can be used to assign different colours.

range.col

Colour of stratigraphic ranges.

extant.col

Colour of extant samples. If show.taxonomy = TRUE, extant.col will be ignored.

taxa.palette

Colour palette used if show.fossils = TRUE. Colours are assigned to taxa using the function grDevices::hcl.colors() and the default palette is "viridis". Other colour blind friendly palettes include "Blue-Red 3" and "Green-Brown".

col.axis

Colour of the time scale axis (default = "gray35").

cex

Numeric value giving the factor used to scale the points representing the fossils when show.fossils = TRUE.

pch

Numeric value giving the symbol used for the points representing the fossils when show.fossils = TRUE.

...

Additional parameters to be passed to plot.default.

Examples

set.seed(123)

## simulate tree
t = TreeSim::sim.bd.taxa(8, 1, 1, 0.3)[[1]]

## simulate fossils under a Poisson sampling process
f = sim.fossils.poisson(rate = 3, tree = t)
plot(f, t)
# add a set of equal length strata
plot(f, t, show.strata = TRUE, strata = 4)
# show stratigraphic ranges
plot(f, t, show.strata = TRUE, strata = 4, show.ranges = TRUE)

## simulate fossils and highlight taxonomy
s = sim.taxonomy(t, 0.5, 1)
f = sim.fossils.poisson(rate = 3, taxonomy = s)
plot(f, t, taxonomy = s, show.taxonomy = TRUE, show.ranges = TRUE)


## simulate fossils under a non-uniform model of preservation
# assign a max interval based on tree height
max.age = tree.max(t)
times = c(0, 0.3, 1, max.age)
rates = c(4, 1, 0.1)
f = sim.fossils.intervals(t, interval.ages = times, rates = rates)
plot(f, t, show.strata = TRUE, interval.ages = times)
# add proxy data
plot(f, t, show.strata = TRUE, interval.ages = times, show.proxy = TRUE, proxy.data = rates)