Calculating Diversity Curves Across Multiple Datasets
Description
Calculates multiple diversity curves from a list of datasets of taxic ranges and/or phylogenetic trees, for the same intervals, for all the individual datasets. A median curve with 95 percent quantile bounds is also calculated and plotted for each interval.
Usage
1 2 3 4 5 6 7 8 9  multiDiv(data, int.length = 1, plot = TRUE, split.int = TRUE,
drop.ZLB = TRUE, drop.cryptic = FALSE, extant.adjust = 0.01,
plotLogRich = FALSE, timelims = NULL, int.times = NULL,
plotMultCurves = FALSE, multRainbow = TRUE, divPalette = NULL,
divLineType = 1, main = NULL)
plotMultiDiv(results, plotLogRich = FALSE, timelims = NULL,
plotMultCurves = FALSE, multRainbow = TRUE, divPalette = NULL,
divLineType = 1, main = NULL)

Arguments
data 
A list where each element is a dataset, formatted to be input in
one of the diversity curve functions listed in 
int.length 
The length of intervals used to make the diversity curve. Ignored if int.times is given. 
plot 
If 
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. 
drop.ZLB 
If true, zerolength terminal branches are dropped from the input tree for phylogenetic datasets, before calculating standing diversity. 
drop.cryptic 
If TRUE, cryptic taxa are merged to form one taxon for
estimating taxon curves. Only works for objects from 
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. 
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. 
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. 
plotMultCurves 
If 
multRainbow 
If 
divPalette 
Can be used so users can pass a vector of chosen color identifiers for each diversity curve in 'data' which will take precedence over multRainbow. Must be the same length as the number of diversity curves supplied. 
divLineType 
Used to determine line type ( 
main 
The main label for the figure. 
results 
The output of a previous run of multiDiv for replotting. 
Details
This function is essentially a wrapper for the individual diversity curve
functions included in paleotree. multiDiv will intuitively decide whether
input datasets are continuoustime taxic ranges, discretetime (binned
interval) taxic ranges or phylogenetic trees, as long as they are formatted
as required by the respective diversity curve functions. A list that
contains a mix of data types is entirely acceptable. A list of matrices
output from fossilRecord2fossilTaxa
, via simulation with simFossilRecord
is allowable, and treated as input for taxicDivCont
.
Data of an unknown type gives back an error.
The argument split.int splits intervals, if and only if discrete interval
time data is included among the datasets. See the help file for taxicDivDisc
to see an explanation of why split.int = TRUE
by default is probably a good
thing.
As with many functions in the paleotree library, absolute time is always decreasing, i.e. the present day is zero.
The 'averaged' curve is actually the median rather than the mean as diversity counts are often highly skewed (in this author's experience).
The shaded certainty region around the median curve is the twotailed 95 percent lower and upper quantiles, calculated from the observed data. It is not a true probabilisitic confidence interval, as it has no relationship to the standard error.
Value
A list composed of three elements will be invisibly returned:
int.times 
A two column matrix giving interval start and end times 
div 
A matrix of measured diversities in particular intervals by rows, with each column representing a different dataset included in the input 
median.curve 
A three column matrix, where the first column is the calculated median curve and the second and third columns are the 95 percent quantile upper and lower bounds 
See Also
The diversity curve functions used include: phyloDiv
,
taxicDivCont
and taxicDivDisc
.
Also see the function LTT.average.root in the package TreeSim, which calculates an average LTT curve for multiple phylogenies, the functions mltt.plot in ape and ltt in phytools.
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  set.seed(444)
record<simFossilRecord(p=0.1, q=0.1, nruns=1,
nTotalTaxa=c(30,40), nExtant=0)
taxa<fossilRecord2fossilTaxa(record)
rangesCont < sampleRanges(taxa, r=0.5)
rangesDisc < binTimeData(rangesCont, int.length=1)
cladogram<taxa2cladogram(taxa, plot=TRUE)
#using multiDiv with very different data types
ttree < timePaleoPhy(cladogram, rangesCont, type="basic", add.term=TRUE, plot=FALSE)
input < list(rangesCont, rangesDisc, ttree)
multiDiv(input, plot=TRUE)
#using fixed interval times
multiDiv(input, int.times=rangesDisc[[1]], plot=TRUE)
#using multiDiv with samples of trees
ttrees < timePaleoPhy(cladogram, rangesCont, type="basic",
randres=TRUE, ntrees=10, add.term=TRUE)
multiDiv(ttrees)
#uncertainty in diversity history is solely due to
#the random resolution of polytomies
#multiDiv can also take output from simFossilRecord, via fossilRecord2fossilTaxa
#what do many simulations run under some set of conditions 'look' like on average?
set.seed(444)
records<simFossilRecord(p=0.1, q=0.1, nruns=10,
totalTime=30, plot=TRUE)
taxa<sapply(records,fossilRecord2fossilTaxa)
multiDiv(taxa)
#increasing cone of diversity!
#Even better on a log scale:
multiDiv(taxa, plotLogRich=TRUE)
#purebirth example with simFossilRecord
#note that conditioning is tricky
set.seed(444)
recordsPB<simFossilRecord(p=0.1, q=0, nruns=10,
totalTime=30,plot=TRUE)
taxaPB<sapply(recordsPB,fossilRecord2fossilTaxa)
multiDiv(taxaPB,plotLogRich=TRUE)
#compare many discrete diversity curves
discreteRanges<lapply(taxa,function(x)
binTimeData(sampleRanges(x, r=0.5,
min.taxa=1), int.length=7))
multiDiv(discreteRanges)
layout(1)
