eED: Calculate expected Evolutionary Distinctiveness (expected ED)...

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

View source: R/eED.R

Description

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.

Usage

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)

Arguments

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.

Value

A list with components:

Background

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".

Normal Use

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.

Future Evolution

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.

Warning

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.

Acknowledgements

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

Author(s)

Matt Davis

References

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.

Examples

1
2
3
4
5
6
7
8
9
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)

ursus-americanus/mallorn documentation built on Oct. 17, 2018, 9:11 p.m.