pez.metrics: Phylogenetic and functional trait metrics within pez

In pez: Phylogenetics for the Environmental Sciences

Phylogenetic and functional trait metrics within pez

Description

Using these functions, you can calculate any of the phylogenetic metrics within pez, using comparative.comm objects. While you can call each individually, using the pez.shape, pez.evenness, pez.dispersion, and pez.dissimilarity wrapper functions (and the more flexible generic.metrics and null model functions) are probably your best bet. Note that *all of these functions* take a common first parameter: a comparative.comm object. There are additional parameters that can be passed, which are described below.

Usage

.hed(x, ...)

.eed(x, na.rm = TRUE, ...)

.psv(x, ...)

.psr(x, ...)

.mpd(x, dist = NULL, abundance.weighted = FALSE, ...)

.vpd(x, dist = NULL, abundance.weighted = FALSE, ...)

.vntd(x, dist = NULL, abundance.weighted = FALSE, ...)

.pd(x, include.root = TRUE, abundance.weighted = FALSE, ...)

.mntd(x, dist = NULL, abundance.weighted = FALSE, ...)

.gamma(x, ...)

.taxon(x, dist = NULL, abundance.weighted = FALSE, ...)

.eigen.sum(x, dist = NULL, which.eigen = 1, ...)

.dist.fd(x, method = "phy", abundance.weighted = FALSE, ...)

.sqrt.phy(x)

.phylo.entropy(x, ...)

.aed(x, ...)

.haed(x, ...)

.simpson.phylogenetic(x)

.iac(x, na.rm = TRUE, ...)

.pae(x, na.rm = TRUE, ...)

.scheiner(x, q = 0, abundance.weighted = FALSE, ...)

.pse(x, ...)

.rao(x, ...)

.lambda(x, ...)

.delta(x, ...)

.kappa(x, ...)

.eaed(x, ...)

.unifrac(x, ...)

.pcd(x, permute = 1000, ...)

.comdist(x, dist = NULL, abundance.weighted = FALSE, ...)

.phylosor(x, dist = NULL, abundance.weighted = FALSE, ...)

.d(x, permute = 1000, ...)

.ses.mpd(
  x,
  dist = NULL,
  null.model = "taxa.labels",
  abundance.weighted = FALSE,
  permute = 1000,
  ...
)

.ses.mntd(
  x,
  dist = NULL,
  null.model = "taxa.labels",
  abundance.weighted = FALSE,
  permute = 1000,
  ...
)

.ses.vpd(
  x,
  dist = NULL,
  null.model = "taxa.labels",
  abundance.weighted = FALSE,
  permute = 1000,
  ...
)

.ses.vntd(
  x,
  dist = NULL,
  null.model = "taxa.labels",
  abundance.weighted = FALSE,
  permute = 1000,
  ...
)

.ses.mipd(
  x,
  dist = NULL,
  null.model = "taxa.labels",
  abundance.weighted = FALSE,
  permute = 1000,
  ...
)

.ses.innd(
  x,
  dist = NULL,
  null.model = "taxa.labels",
  abundance.weighted = FALSE,
  permute = 1000,
  ...
)

.mipd(x, dist = NULL, abundance.weighted = FALSE, ...)

.innd(x, dist = NULL, abundance.weighted = FALSE, ...)

.innd(x, dist = NULL, abundance.weighted = FALSE, ...)

.pe(x, ...)

.bed(x, ...)

Arguments

x	comparative.comm object
...	ignored
na.rm	remove NAs in calculations (altering this can obscure errors that are meaningful; I would advise leaving alone)
dist	distance matrix for use with calculations; could be generated from traits, a square-root-transformed distance matrix (see .sqrt.phy for creating a comparative.comm object with a square-root transformed phylogeny). Default: NULL (–> calculate distance matrix from phylogeny)
abundance.weighted	whether to include species' abundances in metric calculation, often dictating whether you're calculating a pez.shape or pez.evenness metric. Default: FALSE
include.root	include root in PD calculations (default is TRUE, as in picante, but within pez.shape I specify FALSE
which.eigen	which phylo-eigenvector to be used for PVR metric
method	whether to calculate using phylogeny ("phy"; default) or trait data ("traits")
q	the q parameter for .scheiner; default 0.0001
permute	number of permutations of null randomisations (mostly only applies to dispersion metrics)
null.model	one of "taxa.labels", "richness", "frequency", "sample.pool", "phylogeny.pool", "independentswap", or "independentswap". These correspond to the null models available in picante; only d does not use these null models

Details

.pd returns two metrics: Faith's PD (which does not take into account abundance) and Faith's PD corrected for species richness or total abundance (depending on abundance.weighted). I am almost certain that I got the idea for this from somewhere, but I can't find the reference: if you published on this before 2012, please get in touch with me.

.scheiner has a different formula for the case where q is equal to 1 (check the code if interested). The nature of its definition means that values very close to, but not exactly equal to, 1 may be extremely large or extremely small. This is a feature, not a bug, and an inherent aspect of its definition. Check the formula in the code for more information!

Note

Many (but not all) of these functions are fairly trivial wrappers around functions in other packages. In the citations for each metric, * indicates a function that's essentially written in picante. The Pagel family of measures are also fairly trivial wrapper around caper code, functional dissimilarity FD code, gamma, and ape code. I can't demand it, but I would be grateful if you would cite these authors when using these wrappers.

The pez.shape, pez.evenness, pez.dispersion, and pez.dissimilarity wrapper functions go to some trouble to stop you calculating metrics using inappropriate data (see their notes). These functions give you access to the underlying code within pez; there is nothing I can do to stop you calculating a metric that, in my opinion, doesn't make any sense. You have been warned :D

If you're a developer hoping to make your metric(s) work in this framework, please use the argument naming convention for arguments described in this help file, and use the ... operator in your definition. That way functions that don't need particular arguments can co-exist peacefully with those that do. The first argument to one of these functions should always be a comparative.comm object; there is no method dispatch on any of these functions and I foresee future pain without this rule.

References

eed,hed (i.e., Eed, Hed) Cadotte M.W., Davies T.J., Regetz J., Kembel S.W., Cleland E. & Oakley T.H. (2010). Phylogenetic diversity metrics for ecological communities: integrating species richness, abundance and evolutionary history. Ecology Letters, 13, 96-105.

PSV,PSR,PSE Helmus M.R., Bland T.J., Williams C.K. & Ives A.R. (2007). Phylogenetic measures of biodiversity. American Naturalist, 169, E68-E83.

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

gamma Pybus O.G. & Harvey P.H. (2000) Testing macro-evolutionary models using incomplete molecular phylogenies. _Proceedings of the Royal Society of London. Series B. Biological Sciences 267: 2267–2272.

taxon Clarke K.R. & Warwick R.M. (1998). A taxonomic distinctness index and its statistical properties. J. Appl. Ecol., 35, 523-531.

eigen.sum Diniz-Filho J.A.F., Cianciaruso M.V., Rangel T.F. & Bini L.M. (2011). Eigenvector estimation of phylogenetic and functional diversity. Functional Ecology, 25, 735-744.

entropy Allen B., Kon M. & Bar-Yam Y. (2009). A New Phylogenetic Diversity Measure Generalizing the Shannon Index and Its Application to Phyllostomid Bats. The American Naturalist, 174, 236-243.

pae,aed,iac,haed,eaed Cadotte M.W., Davies T.J., Regetz J., Kembel S.W., Cleland E. & Oakley T.H. (2010). Phylogenetic diversity metrics for ecological communities: integrating species richness, abundance and evolutionary history. Ecology Letters, 13, 96-105.

scheiner Scheiner, S.M. (20120). A metric of biodiversity that integrates abundance, phylogeny, and function. Oikos, 121, 1191-1202.

rao Webb C.O. (2000). Exploring the phylogenetic structure of ecological communities: An example for rain forest trees. American Naturalist, 156, 145-155.

lambda,delta,kappa Mark Pagel (1999) Inferring the historical patterns of biological evolution. Nature 6756(401): 877–884.

unifrac Lozupone C.A. & Knight R. (2005). UniFrac: a new phylogenetic method for comparing microbial communities. Applied and Environmental Microbiology, 71, 8228-8235.

pcd Ives A.R. & Helmus M.R. (2010). Phylogenetic metrics of community similarity. The American Naturalist, 176, E128-E142.

comdist C.O. Webb, D.D. Ackerly, and S.W. Kembel. 2008. Phylocom: software for the analysis of phylogenetic community structure and trait evolution. Bioinformatics 18:2098-2100.

phylosor Bryant J.A., Lamanna C., Morlon H., Kerkhoff A.J., Enquist B.J. & Green J.L. (2008). Microbes on mountainsides: Contrasting elevational patterns of bacterial and plant diversity. Proceedings of the National Academy of Sciences of the United States of America, 105, 11505-11511.

d Fritz S.A. & Purvis A. (2010). Selectivity in Mammalian Extinction Risk and Threat Types: a New Measure of Phylogenetic Signal Strength in Binary Traits. Conservation Biology, 24, 1042-1051.

sesmpd,sesmntd Webb C.O. (2000). Exploring the phylogenetic structure of ecological communities: An example for rain forest trees. American Naturalist, 156, 145-155.

innd,mipd Ness J.H., Rollinson E.J. & Whitney K.D. (2011). Phylogenetic distance can predict susceptibility to attack by natural enemies. Oikos, 120, 1327-1334.

PE Rosauer, D. A. N., Laffan, S. W., Crisp, M. D., Donnellan, S. C., & Cook, L. G. (2009). Phylogenetic endemism: a new approach for identifying geographical concentrations of evolutionary history. Molecular Ecology, 18(19), 4061-4072.

BED Cadotte, M. W., & Jonathan Davies, T. (2010). Rarest of the rare: advances in combining evolutionary distinctiveness and scarcity to inform conservation at biogeographical scales. Diversity and Distributions, 16(3), 376-385.

Examples

data(laja)
data <- comparative.comm(invert.tree, river.sites)
.psv(data)

pez documentation built on Sept. 1, 2022, 1:09 a.m.