ePD: Calculate expected Phylogenetic Diversity (expected PD) for...
In ursus-americanus/mallorn: Compute Probabilistic Phylogenetic Diversity Metrics

Description Usage Arguments Value Background Normal Use Future Evolution Warning Acknowledgements Author(s) References Examples

ePD calculates the expected Phylogenetic Diversity (expected PD) for one or more communities of taxa and can include expected future evolution.

1
2
3

ePD(tree = NA, probabilities.tips.present.matrix = NULL, lambda = NULL,
  mu = NULL, tMa = 0, auto.save = F, save.tree = F,
  save.tip.probabilites = F, source.of.data = NA)

`tree`	An object of class phylo.
`probabilities.tips.present.matrix`	A taxon by community matrix of presence probabilities for each tip of the tree. Each row is a taxon. Each column is a community (or temporal bin). Taxa names must match the tip labels of the tree. If no probabilites are supplied, all tips are assumed present and PD is calculated.
`lambda`	Numeric. A single instantaneous speciation rate in lineages per million species years.
`mu`	Numeric. A single instantaneous extinction rate in lineages per million species years.
`tMa`	Numeric. How many millions of years into the future will expected PD be calculated at? For normal function use where one is just looking at expected PD without any future evolution, tMa should be 0.
`auto.save`	Logical. Automatically write the output of the function to the working directory?
`save.tree`	Logical. Automatically save the tree used with the model output?
`save.tip.probabilites`	Logical. Automatically save the probabilites that tips are present in the model output?
`source.of.data`	Character. Optional data tag to include in the function output.

A list with components:

community.values A matrix with expected Phylogenetic Diversity (expected PD) and expected species richness for each community

Expected.Phylo.Diversity.Ma
The expected PD in millions of years of evolution. This will include new evolution if tMa does not equal 0.

Expected.Species.Diversity
The expected taxonomic richness. This is really the expected number of tips so depending on the taxonomic resolution of your tree, this could be species, subspecies, or whole orders. This will include newly evolved tips if tMa does not equal 0.
lambda The original speciation rate input
mu The original extinction rate input
tMa The original timespan input in millions of years
source.of.data Optional data tag from input
probabilities.tips.present.matrix The original taxon by community matrix of presence probabilities. Only present in ouput if save.tip.probabilites=T
tree The original phylo object input. Only present in output if save.tree=T

Phylogenetic Diversity (PD) (Faith, 1992) is a biodiversity metric that measures the total amount of evolutionary history in a community. It is defined as the sum of all branch lengths neccesary to connect a given set of taxa to the root of a phylogenetic tree and can be calculated in the function pd. PD assumes that all tips have a probability of 1 of being measured, though.

Expected Phylogenetic Diversity (expected PD) is the probabilistic implementation of PD (Faith, 2008). Expected PD is the expected amount of evolutionary history contained in a community. Each tip is given a probability of being present (from 0=absent to 1=present) that could reflect the taxon's actual survival probability (e.g. IUCN Red List Rank), output of a species distribution model, or the probability of sampling this taxon in a certain community. Note that if each tip is given a probability of 1 of being present, expected PD simplifies to PD and this function will return the same results as pd.

Typical usage is

ePD(tree, probabilities.tips.present.matrix)

This will calculate expected PD on a tree without any projected future evolution. Most users will only need to designate a tree and a matrix of probabilties that species are present named with labels that match the tip labels in the tree. The time tMa=0 is set by default.

Note that expected PD is simply the sum of each tip's expected Evolutionary Distinctiveness (expected ED) in a community. ePD is a convenience function to save you time if you don't care about individual taxon values. However, if you have already calculated expected Evolutionary Distinctiveness in eED, you can get the same results as ePD by using sum(tip.values$Expected.Evol.Distinct.Ma). This may save you time if you are working with very large trees. If all your tip extinction probabilities are binary (0 or 1), you should just use pd, which will likely be much faster than ePD.

ePD should not be confused with the picante function expected.pd. expected.pd calculates the amount of PD expected given taxonomic richness. It is not a implementation of Faith's (2008) probabilistic PD like ePD.

This function can also calculate expected PD given future evolution using a birth-death framework developed by (Mooers et al., 2012). The user must also enter an extinction rate (mu) and specation rate (lambda) in lineages per million species years and a timespan (tMa) in millions of years. The function calculates average expected new branch lengths (evolution in the future) for each tip and probabilites that lineages will go extinct within the timespan tMa. These values are incorportated into the calculation of expected PD. When considering future evolution, the initial presence probabilities that are loaded into the function are the probabilities that the tips are present at 0 million years in the future (i.e. the present), not at some time in the distant future which is determined by the function iteself once tMa is set. Note that considering future evolution really only makes sense on large global phylogenies. This is not a feature that a typical user will need.

This function has been tested only on ultrametric, fully resolved phylogenetic trees. Technically, expected PD could be measured on non-ultrametric trees where branch lengths are scaled to something besides time (e.g. number of nucleotide substitutions) but results will be meaningless if you include future evolution. Use non-resovled and non-ultrametric trees at your own peril. Ultrametricity is checked by a call to is.ultrametric but the default tolerance has been set to 0.000001 because a phylogeny where tip-to-root distances vary by no more than 1 millionth of the age of the tree seems ultrametric enough.

This function uses code and internal functions from the picante (Kembel et al., 2010) and ape (Paradis et al., 2004) packages.

Matt Davis

Faith, D. P. (1992). Conservation evaluation and phylogenetic diversity. Biological Conservation, 61(1), 1–10.

Faith, D. P. (2008). Threatened species and the potential loss of phylogenetic diversity: conservation scenarios based on estimated extinction probabilities and phylogenetic risk analysis. Conservation Biology, 22(6), 1461–1470.

Kembel, S. W., Cowan, P. D., Helmus, M. R., Cornwell, W. K., Morlon, H., Ackerly, D. D., et al. (2010). Picante: R tools for integrating phylogenies and ecology. Bioinformatics, 26(11), 1463–1464.

Mooers, A., Gascuel, O., Stadler, T., Li, H., & Steel, M. (2012). Branch lengths on birth–death trees and the expected loss of phylogenetic diversity. Systematic Biology, 61(2), 195–203.

Paradis, E., Claude, J. and Strimmer, K. (2004) APE: analyses of phylogenetics and evolution in R language. Bioinformatics, 20, 289–290.

data(bear_tree)
data(bear_matrix)

# Normal usage (without future evolution)
ePD(tree=bear_tree, probabilities.tips.present.matrix=bear_matrix)

# Usage with future evolution
# Note that it would not make sense to consider future evolution on a tree this small
ePD(tree=bear_tree, probabilities.tips.present.matrix=bear_matrix, lambda=0.276, mu=0.272, tMa=2)