simFossilRecordMethods: Methods for Editing or Converting Output from simFossilRecord

Description

These are a set of functions available for manipulating, translating and editing the objects of class fossilRecordSimulation output from function simFossilRecord.

Usage

timeSliceFossilRecord(fossilRecord, sliceTime, shiftRoot4TimeSlice = FALSE,
  modern.samp.prob = 1, tolerance = 10^-4)

fossilRecord2fossilTaxa(fossilRecord)

fossilRecord2fossilRanges(fossilRecord, merge.cryptic = TRUE,
  ranges.only = TRUE)

Arguments

fossilRecord

A list object output by simFossilRecord, often composed of multiple elements, each of which is data for 'one taxon', with the first element being a distinctive six-element vector composed of numbers, corresponding to the six numbers in a <

sliceTime

The date to slice the simFossilRecord output at, given in time-units before the modern, on the same scale as the input fossilRecord.

shiftRoot4TimeSlice

Should the dating of events be shifted, so that the date given for sliceTime is now 0, or should the dates not be shifted, so that they remain on the same scale as the input? This argument accepts a logical TRUE or FALSE, but also accepts

modern.samp.prob

The probability that a taxon is sampled at the modern time (or, for timeSliceFossilRecord, the time at which the simulation data is slice). Must be a number between 0 and 1. If 1, all taxa that survive to the modern day (to the slice

tolerance

A small number which sets a range around the sliceTime within which taxa will be considered extant for the purposes of output.

merge.cryptic

If TRUE, sampling events for cryptic taxon-units (i.e. those in the same cryptic complex) will be merged into sampling events for a single taxon-unit (with the name of the first taxon in that cryptic complex).

ranges.only

If TRUE (the default), fossilRecord2fossilRanges will return the dates of the first and last sampled occurrences of each taxon-unit (i.e. the stratigraphic range of each taxon). If FALSE, instead a list will be ou

Value

Depends on the function and the arguments given. See Details.

Details

These functions exist to manipulate fossilRecordSimulation objects output from simFossilRecord, particularly so that they can be interfaced with functions in library paleotree in the same way that output from the legacy simulation function simFossilTaxa was used. timeSliceFossilRecord takes a given fossilRecordSimulation object and 'slices' the data to remove any events that occur after the given sliceTime and make it so any taxa still alive as of sliceTime are now listed as extant. fossilRecord2fossilTaxa converts a fossilRecordSimulation object to the flat table format of taxon data as was originally output by simFossilTaxa simulations, and can be taken as input by a number of paleotree functions such as sampleRanges,taxa2phylo and taxa2cladogram. fossilRecord2fossilRanges converts a fossilRecordSimulation object to the flat table format of observed taxon ranges, as is typically output by processing simulation output (particularly from simFossilTaxa) with paleotree function sampleRanges.

Examples

Run this code

set.seed(44)
record <- simFossilRecord(p=0.1, q=0.1, r=0.1, nruns=1,
	nTotalTaxa=c(20,30) ,nExtant=0, plot=TRUE)

# time-slicing

# let's try slicing this record at 940 time-units
slicedRecord<-timeSliceFossilRecord(fossilRecord = record, sliceTime = 940)
# and let's plot it
divCurveFossilRecordSim(slicedRecord)

# now with shiftRoot4TimeSlice = TRUE to shift the root age
slicedRecord<-timeSliceFossilRecord(fossilRecord = record, sliceTime = 940,
	shiftRoot4TimeSlice = TRUE)
# and let's plot it
divCurveFossilRecordSim(slicedRecord)

# plot look a little different due to how axis limits are treated...
# notice that in both, 'modern' (extant) taxa are sampled with probability = 1
	#let's try it again, make that probability = 0

# now with shiftRoot4TimeSlice=TRUE
slicedRecord<-timeSliceFossilRecord(fossilRecord = record, sliceTime = 940,
	shiftRoot4TimeSlice = TRUE, modern.samp.prob = 0)
# and let's plot it
divCurveFossilRecordSim(slicedRecord)

############################

# converting to taxa objects and observed ranges

# convert to taxa data
taxa<-fossilRecord2fossilTaxa(record)
# convert to ranges
ranges<-fossilRecord2fossilRanges(record)

# plot diversity curves with multiDiv
multiDiv(list(taxa,ranges),plotMultCurves=TRUE)
# should look a lot like what we got earlier

# get the cladogram we'd obtain for these taxa with taxa2cladogram
cladogram<-taxa2cladogram(taxa,plot=TRUE)

# now get the time-scaled phylogenies with taxa2phylo

# first, with tips extending to the true times of extinction
treeExt<-taxa2phylo(taxa,plot=TRUE)

# now, with tips extending to the first appearance dates (FADs) of taxa
	# get the FADs from the ranges
FADs<-ranges[,1]
treeFAD<-taxa2phylo(taxa,FADs,plot=TRUE)