eED: Calculate expected Evolutionary Distinctiveness (expected ED)...
In ursus-americanus/mallorn: Compute Probabilistic Phylogenetic Diversity Metrics

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

eED calculates the expected Evolutionary Distinctiveness (expected ED) for each tip of a phylogenetic tree given presence probabilities for each tip, speciation and extinction rates, and a time into the future. It also calculates several other values for each edge of the tree like probability of extinction and number of subtending daughter tips.

1
2
3

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

`tree`	An object of class phylo.
`probabilities.tips.present`	A named numeric vector giving the probabilities that each tip of the tree is present. Names must match the tip labels of the tree. If no probabilites are supplied, all tips are assumed present and ED 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 ED be calculated at? For normal function use where one is just looking at expected ED 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?
`source.of.data`	Character. Optional data tag to include in the function output.

A list with components:

tip.values A data.frame containing values for each tip

Label
Names for each tip that match tree labels.

Prob.Tip.Survive.0
The probability that a tip is extant/present at the start of the analysis. These are the probabilities of tips being present that were entered by the user in the function call.

Prob.Tip.Extinct.0
The probability that a tip is extinct/not present at the start of the analysis.

Prob.Tip.Extinct.t
The probability that a tip (or rather the lineage descended from that tip) is extinct by tMa into the future. If tMa is not designated, these probabilities will be the same as Prob.Tip.Extinct.0.

Prob.Tip.Survive.t
The probability that a tip (or rather the lineage descended from that tip) survives tMa into the future. If tMa is not designated, these probabilities will be the same as Prob.Tip.Survive.0.

Expected.Evol.Distinct.Ma.no.new
The Expected Evolutionary Distinctiveness (expected ED) for a tip (in units of millions of years of unique evolution) without any new evolution into the future. This is the value most users will want to use for expected ED.

Expected.Evol.Distinct.Ma
Expected ED for each tip (or rather the lineage descended from that tip) that includes new branch lengths generated through evolution until tMa into the future. Measured in units millions of years of unique evolution. If tMa=0, this will be the same as Expected.Evol.Distinct.Ma.no.new as new evolution was not considered.

Expected.Evol.Distinct.perc
Expected ED for each tip (or rather the lineage descended from that tip) as a percent of total tree Phylogenetic Diversity (PD). In other words, what percentage of the total tree can be attributed to each tip. Note that this will include new evolution if tMa does not equal 0!

Expected.Evol.Distinct.Ma.loss
How much of the expected loss of PD (from a scenario where all tips on the tree are present) can be attributed to each tip (in units of millions of years of unique evolution). Expected.Evol.Distinct.Ma is how much ED we expect a tip to retain, and Expected.Evol.Distinct.Ma.loss is how much ED we expect a tip to lose. Note that this will not include new evolution per se because new lineages that don't survive until tMa are not counted as losses. A tip can't lose more ED than it started out with at tMa=0. If tMa=0, the sum of each tip's Expected.Evol.Distinct.Ma and Expected.Evol.Distinct.Ma.loss will equal PD.

Expected.Evol.Distinct.perc.loss
The expected loss in ED for each tip as a percentage of total tree PD. Note that this will not include new evolution per se because new lineages that don't survive until tMa are not counted as losses. A tip can't lose more ED than it started out with at tMa=0.

Pendant.Edge.Ma
The length of a tip's pendant edge in units of millions of years of unique evolution. If tips are species, this is the age of the species. Note that this does not include future evolution regardless of what tMa equals.

Expected.Pendant.Edge.Ma.loss
How much of a tip's pendant edge is expected to be lost (in units of millions of years of unique evolution). For example, if a species has a .74 probability of extinction by tMa, we would expect 74 % of the pendant edge to be lost. Note that this does not include branch lengths from future evolution regardless of what tMa equals but it will use the Prob.Tip.Extinct.t to calculate the expected loss not Prob.Tip.Extinct.0 if tMa does not equal 0. This means that Expected.Pendant.Edge.Ma.loss is the amount of the tip's original pendant edge that we would expect to lose given any future evolution.
edge.values A data.frame containing values for each edge

Node
The name of the tipward node connected to the edge. This is where an edge ends.

Daughters
The number of daughter tips subtending a node.

Edge.Length.Ma
The length of the edge in units of millions of years.

Edge.Age.Ma
The age of the edge in millions of years in the past. This is the age where the edge starts, the rootward node of an edge.

Prob.Edge.Extinct.t
The probability that an edge will go extinct by tMa into the future. An edge only goes extinct if all tips subtending that edge go extinct.

Prob.Edge.Survive.t
The probability that an edge will survive until tMa into the future.

Expected.Edge.Length.Ma
The expected length of an edge in units of millions of years given the probability the edge will survive until tMa. For example, if an edge only has a 25 % chance of surviving until tMa, we would only expect 25 % of its length to remain.

Expected.Edge.Length.Ma.loss
The expected loss of length of an edge in units of millions of years given the probability the edge will survive until tMa. For example, if an edge only has a 25 % chance of surviving until tMa, we would expect 75 % of its length to be lost.
tree The original phylo object input. Only present in output if save.tree=T.
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

Evolutionary Distinctiveness (ED) (Redding et al., 2014) fairly apportions Phylogenetic Diversity (PD) among tips of a phylogenetic tree and can be calculated in the function evol.distinct. From Redding et al. (2014), ED "...for species i is the sum of edge lengths along the path from i to the root, each edge divided by the number of species ultimately subtending it". Thus, ED is the amount of unique evolutionary history that can be attributed to each tip. ED assumes that all tips have a probability of 1 of being measured, though.

Expected Evolutionary Distinctiveness (expected ED) is the probabilistic implementation of ED so that expected ED is the expected amount of unique evolutionary history that can be attributed to each tip. The sum of all tip's ED values in a tree will equal PD but the sum of all tip's expected ED values will equal expected PD (Faith, 2008). 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 ED simplifies to ED and this function will return the same results as evol.distinct, type="fair.proportion".

Typical usage is

eED(tree, probabilities.tips.present)

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

This function can also calculate expected ED 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 ED. 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 ED 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. (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.

Redding, D. W., Mazel, F., & Mooers, A. Ø. (2014). Measuring evolutionary isolation for conservation. PLoS ONE, 9(12), e113490.

data(bear_tree)
data(bear_probs)

# Normal usage (without future evolution)
eED(tree=bear_tree, probabilities.tips.present=bear_probs)

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