Diversity Curves
Description
Functions to plot diversity curves based on taxic range data, in both discrete and continuous time, and for phylogenies.
Usage
1 2 3 4 5 6 7 8 9  taxicDivCont(timeData, int.length = 1, int.times = NULL, plot = TRUE,
plotLogRich = FALSE, timelims = NULL, drop.cryptic = FALSE)
taxicDivDisc(timeList, int.times = NULL, drop.singletons = FALSE,
plot = TRUE, plotLogRich = FALSE, timelims = NULL,
extant.adjust = 0.001, split.int = TRUE)
phyloDiv(tree, int.length = 0.1, int.times = NULL, plot = TRUE,
plotLogRich = FALSE, drop.ZLB = TRUE, timelims = NULL)

Arguments
timeData 
Twocolumn matrix giving the pertaxon first and last
appearances in absolute time. The simulated data tables output by 
int.length 
The length of intervals used to make the diversity curve. Ignored if int.times is given. 
int.times 
An optional twocolumn matrix of the interval start and end times for calculating the diversity curve. If NULL, calculated internally. If given, the argument split.int and int.length are ignored. 
plot 
If TRUE, a diversity curve generated from the data is plotted. 
plotLogRich 
If TRUE, taxic diversity is plotted on log scale. 
timelims 
Limits for the x (time) axis for diversity curve plots. Only affects plotting. Given as either NULL (the default) or as a vector of length two as for 'xlim' in the basic R function plot. Time axes will be plotted exactly to these values. 
drop.cryptic 
If TRUE, cryptic taxa are merged to form one taxon for
estimating taxon curves. Only works for objects from 
timeList 
A list composed of two matrices, giving interval start and end dates and taxon first and last occurrences within those intervals. See details. 
drop.singletons 
If TRUE, taxa confined to a single interval will be dropped prior to the diversity curve calculation. This is sometimes done if single intervals have overly high diversities due to the 'monograph' effect where more named taxa are known in certain intervals largely due to taxonomic expert effort and not real changes in historical biotic diversity. 
extant.adjust 
Amount of time to be added to extend start time for (0,0) bins for extant taxa, so that the that 'time interval' doesn't appear to have an infinitely small width. 
split.int 
For discrete time data, should calculated/input intervals be split at discrete time interval boundaries? If FALSE, can create apparent artifacts in calculating the diversity curve. See below. 
tree 
A timescaled phylogeny of class phylo. 
drop.ZLB 
If true, zerolength terminal branches are dropped from the input tree for phylogenetic datasets, before calculating standing diversity. 
Details
First, some background. Diversity curves are plots of species/taxon/lineage richness over time for a particular group of organisms. For paleontological studies, these are generally based on pertaxon range data while more recently in evolutionary biology, molecular phylogenies have been used to calculate lineagethroughtime plots (LTTs). Neither of these approaches are without their particular weaknesses; reconstructing the true history of biodiversity is a difficult task no matter what data is available.
The diversity curves produced by these functions will always measure diversity within binned time intervals (and plot them as rectangular bins). For continuoustime data or phylogenies, one could decrease the int.length used to get what is essentially an 'instantaneous' estimate of diversity. This is warned against, however, as most historical diversity data will have some timeaveraging or uncertain temporal resolution and thus is probably not finelyresolved enough to calculate instantaneous estimates of diversity.
As with many functions in the paleotree library, absolute time is always decreasing, i.e. the present day is zero.
As diversity is counted within binned intervals, the true standing diversity may be somewhat lower than the measured (observed) quantity, particularly if intervals are longer than the mean duration of taxa is used. This will be an issue with all diversity curve functions, but particularly the discretetime variant. For diversity data in particularly large discrete time intervals, plotting this data in smaller bins which do not line up completely with the original intervals will create a 'spiky' diversity curve, as these smaller intersecting bins will have a large number of taxa which may have been present in either of the neighboring intervals. This will give these small bins an apparently high estimated standing diversity. This artifact is avoided with the default setting split.int=TRUE, which will split any input or calculated intervals so that they start and end at the boundaries of the discretetime range bins.
The timeList object should be a list composed of two matrices, the first
matrix giving byinterval start and end times (in absolute time), the second
matrix giving the bytaxon first and last appearances in the intervals
defined in the first matrix, numbered as the rows. Absolute time should be
decreasing, while the intervals should be numbered so that the number
increases with time. Taxa alive in the modern should be listed as last
occurring in a time interval that begins at time 0 and ends at time 0.
See the documentation for the timescaling function
bin_timePaleoPhy
and the simulation function
binTimeData
for more information on formatting.
Unlike some paleotree functions, such as perCapitaRates, the intervals can be overlapping or of unequal length. The diversity curve functions deal with such issues by assuming taxa occur from the base of the interval they are first found in until the end of the last interval they are occur in. Taxa in wideranging intervals that contain many others will be treated as occurring in all nested intervals.
phyloDiv will resolve polytomies to be dichotomous nodes separated by zerolength branches prior to calculating the diversity curve. There is no option to alter this behavior, but it should not affect the use of the function because the addition of the zerolength branches should produce an identical diversity history as a polytomy. phyloDiv will also drop zerolength terminal branches, as with the function dropZLB. This the default behavior for the function but can be turned off by setting the argument drop.zlb to FALSE.
Value
These functions will invisibly return a threecolumn matrix, where the first two columns are interval start and end times and the third column is the number of taxa/lineages counted in that interval.
Author(s)
David W. Bapst
See Also
multiDiv
, timeSliceTree
,
binTimeData
There are several different functions for traditional LTT plots
(phylogenetic diversity curves), such as the function
,ltt.plot
in the package ape, the function ltt
in the
package phytools, the function plotLtt
in the package laser and the
function LTT.average.root
in the package TreeSim.
Examples
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70  #taxicDivDisc with the retiolinae dataset
data(retiolitinae)
taxicDivDisc(retioRanges)
#simulation examples
set.seed(444)
record<simFossilRecord(p=0.1, q=0.1, nruns=1,
nTotalTaxa=c(30,40), nExtant=0)
taxa<fossilRecord2fossilTaxa(record)
#let's see what the 'true' diversity curve looks like in this case
#plot the FADs and LADs with taxicDivCont()
taxicDivCont(taxa)
#simulate a fossil record with imperfect sampling with sampleRanges
rangesCont < sampleRanges(taxa,r=0.5)
#plot the diversity curve based on the sampled ranges
layout(1:2)
taxicDivCont(rangesCont)
#Now let's use binTimeData to bin in intervals of 1 time unit
rangesDisc < binTimeData(rangesCont,int.length=1)
#plot with taxicDivDisc
taxicDivDisc(rangesDisc)
#compare to the continuous time diversity curve
layout(1)
#Now let's make a tree using taxa2phylo
tree < taxa2phylo(taxa,obs_time=rangesCont[,2])
phyloDiv(tree)
#a simple example with phyloDiv
#using a tree from rtree in ape
set.seed(444)
tree < rtree(100)
phyloDiv(tree)
#a neat example of using phyDiv with timeSliceTree
#to simulate doing molecularphylogeny studies
#of diversification...in the past
set.seed(444)
record<simFossilRecord(p=0.1, q=0.1, nruns=1,
nTotalTaxa=c(30,40), nExtant=0)
taxa<fossilRecord2fossilTaxa(record)
taxicDivCont(taxa)
#that's the whole diversity curve
#with timeSliceTree we could look at the lineage accumulation curve
#we'd get of species sampled at a point in time
tree < taxa2phylo(taxa)
#use timeSliceTree to make tree of relationships up until time=950
tree950 < timeSliceTree(tree,sliceTime=950,plot=TRUE,drop.extinct=FALSE)
#use drop.extinct=T to only get the tree of lineages extant at time=950
tree950 < timeSliceTree(tree,sliceTime=950,plot=TRUE,drop.extinct=TRUE)
#now its an ultrametric tree with many fewer tips...
#lets plot the lineage accumulation plot on a log scale
phyloDiv(tree950,plotLogRich=TRUE)
#an example of a 'spiky' diversity curve and why split.int is a good thing
set.seed(444)
record<simFossilRecord(p=0.1, q=0.1, nruns=1,
nTotalTaxa=c(30,40), nExtant=0)
taxa<fossilRecord2fossilTaxa(record)
taxaDiv < taxicDivCont(taxa)
#simulate a fossil record with imperfect sampling with sampleRanges()
rangesCont < sampleRanges(taxa,r=0.5)
rangesDisc < binTimeData(rangesCont,int.length=10)
#now let's plot with taxicDivDisc() but with the intervals from taxaDiv
#by default, split.int=TRUE
taxicDivDisc(rangesDisc,int.times=taxaDiv[,1:2],split.int=TRUE)
#look pretty
#now let's turn off split.int
taxicDivDisc(rangesDisc,int.times=taxaDiv[,1:2],split.int=FALSE)
#looks 'spiky'!
