divRates: Calculate sensitivity of absolute diversification rates to...

In eliotmiller/addTaxa: An R package for adding missing taxa to phylogenies

Calculate sensitivity of absolute diversification rates to missing taxa

Description

Given a data frame of species and taxonomic assignments, an accepted phylogeny with some of those species in it, and a number of named, monophyletic clades, will add missing species next to a taxonomic relatives and quantify sensitivity of clade-specific absolute diversification rates.

Usage

divRates(tree, groupings, branch.position, ini.lambda = 1, ini.mu = 0.1,
  bd.type, rate.estimate, local.cutoff, time.out, no.trees, clade.membership,
  crown.can.move, calc.from.crown, epsilon)

Arguments

tree	An ape-style phylogenetic tree
groupings	A data frame with two columns, "species" and "group". Missing species, to be added, are taken as those that do not match a value in the tip labels of tree.
branch.position	Once the algorithm has selected to which node a species will be bound, this determines where on the branch that happens. Note that this refers to the position below (stemwards) from the node the tip will be bound.Currently there are four options. The first, "polytomy", creates a polytomy at the node to which the new tip is added (need to check but it might actually make a dichotomous branch of length 0). The second, "midpoint", simply splits the difference between the node and its parent and binds the new tip in there. The third, "uniform", will sample from a uniform distribution with a minimum of zero and a maximum of the full distance between the node and its parent. Note that this means that species can conceivably be added at the maximum or minimum distance possible from the tip, which would create a polytomy (or branch of length 0?). I have removed checks to account and deal with this–if you need them back let me know. The fourth option is "bd." This uses the corsim function from the TreeSim package to simulate the missing speciation events according to speciation (lambda) and extinction (mu) values passed to addTaxa.
ini.lambda	Initial speciation value for the "bd" optimization, if that option of branch position is chosen. Defaults to 1.
ini.mu	Initial extinction value for the "bd" optimization, if that option of branch position is chosen. Defaults to 0.1.
bd.type	Whether to use a 'local' or a 'global' birth-death estimation. The former is slower but tends to perform better, particularly if there are shifts in diversification rates in the tree. The latter runs faster.
rate.estimate	Whether to use 'laser', 'ape', or 'diversitree' to calculate diversification rates. The latter is the only of those that can account for missing taxa, but in my experience returns systematically biased values.
local.cutoff	If using the local form of the bd method, this argument specifies at what point the local neighborhood is deemed sufficiently large to estimate a local diversification rate. For example, if this argument is set to 10, a local estimate is not derived until the species being added is being bound into a monophyletic clade of at least 10 tips belonging to that species' group. The method seems to perform better when this cutoff is set low, but smaller numbers increase run time. The cutoff must be 3 or higher, as the birth-death estimation will always fail for two taxa. It can also fail or timeout (see below) for larger cutoffs–when it does, it uses the midpoint branch.position method and moves onto the next taxon.
time.out	The amount of time to sample in search of a new branch position that accords with the local birth death estimation and that falls within the age of the branch to which the new species is being bound. Larger values may increase accuracy, but definitely increase run time. Default is 2 seconds.
no.trees	The number of desired final trees with all missing species from groupings added.
clade.membership	An optional data frame with first column = "species", second column = "clade". These are named, monophyletic clades to which the species in the input phylogeny can belong. Not every species in the input phylogeny needs to be in the clade membership data frame, but missing species added to species not in this frame will not be included in the output clade membership data frame. Such species will still be included in the output phylogenies. Note that these clades need to be mutually exclusive. For example, clade 2 cannot be contained within clade 1.
crown.can.move	Logical. If TRUE, and if missing taxa are to be added stemwards, this will allow the age of the crown group to potentially shift back in time. If FALSE, and if missing taxa were to be added stemwards, this will prevent taxa from being added below the crown group. It will force these to be bound crownwards if the crown node in the clade is selected to be bound to. Note that the argument name is somewhat misleading in that the crown ages can still shift when missing taxa are added. Specifically, if missing taxa are bound to what were initially single-species clades in the input tree, then the crown age will "shift" forward in time (the single-taxon clade did not actually have a crown age). If crown.can.move is set to FALSE, then after one taxon is added to such a single-species clade, the crown age of that clade then becomes fixed and will not move.
calc.from.crown	Whether the crown or stem method of bd.ms from geiger will be used.
epsilon	The extinction rate parameter for bd.ms

Details

Adds missing taxa according to all rules and details outlined in addTaxa(). During this process, it tabulates to which named clades missing species are added, and calculates the diversification rate of each clade after each complete tree is created. In this way, the sensitivity of these absolute diversification rates to missing taxa can be assessed.

Value

A dataframe where each row corresponds to a complete tree, and each column corresponds to the calculated absolute diversification rate of a named clade.

References

Mast et al. 2015. Paraphyly changes understanding of timing and tempo of diversification in subtribe Hakeinae (Proteaceae), a giant Australian plant radiation. American Journal of Botany.

Examples

data(chelonia)
tree <- chelonia$phy

#some species in this tree are identified to subspecies. drop those
temp <- lapply(strsplit(tree$tip.label, "_"), length)
names(temp) <- tree$tip.label
temp <- temp[temp==2]
tree <- drop.tip(tree, setdiff(tree$tip.label, names(temp)))

#create an example groupings data frame.
groupsDF <- data.frame(species=tree$tip.label)
groupsDF$group <- unlist(lapply(strsplit(tree$tip.label, "_"), "[", 1))

#drop 20 species from the tree
example <- tipDropper(tree, groupsDF, 20)

#create a dummy data frame to pay attention to diversification rates
#of two arbitrary clades
graptemysEtc <- data.frame(
  species=c(example$tip.label[grep("Graptemys", example$tip.label)],
  example$tip.label[grep("Trachemys", example$tip.label)],
  example$tip.label[grep("Malaclemys", example$tip.label)]),
  clade="graptemys")
gopherus <- data.frame(
  species=example$tip.label[grep("Gopherus", example$tip.label)],
  clade="gopherus")
cladesDF <- rbind(graptemysEtc, gopherus)

#use the divRates function to examine the sensitivity of diversification rates
#to the addTaxa function
sensitivity <- divRates(tree=example, groupings=groupsDF, branch.position="bd",
  bd.type="global", no.trees=3, clade.membership=cladesDF, crown.can.move=TRUE,
  calc.from.crown=TRUE, epsilon=0.1, rate.estimate="ape")

eliotmiller/addTaxa documentation built on Feb. 3, 2024, 12:19 a.m.