pez.dissimilarity {pez}

Calculate (phylogenetic) dissimilarity: compare assemblages to one-another

Description

As described in Pearse et al. (2014), a dissimilarity metric compares diversity between communities. WARNING: Phylosor is presented as a distance matrix here, i.e. it is *not* the fraction of shared branch length among communities, but rather '1 - shared branch length'. This means dissimilarity always returns a *distance* object, not a similarity object; this is a different convention from other packages.

Usage

pez.dissimilarity(
  data,
  metric = c("all", "unifrac", "pcd", "phylosor", "comdist"),
  abundance.weighted = FALSE,
  permute = 1000,
  sqrt.phy = FALSE,
  traitgram = NULL,
  traitgram.p = 2,
  ext.dist = NULL,
  ...
)

Arguments

data

comparative.comm object

metric

default (all) calculates everything; individually call-able metrics are: unifrac, pcd, phylosor, comdist.

abundance.weighted

If TRUE (default is FALSE) metrics are calculated incorporating species abundances; only comdist can incorporate abundances

permute

Number of permutations for metric (currently only for pcd)

sqrt.phy

If TRUE (default is FALSE) your phylogenetic distance matrix will be square-rooted; specifying TRUE will force the square-root transformation on phylogenetic distance matrices (in the spirit of Leitten and Cornwell, 2014). See ‘details’ for details about different metric calculations when a distance matrix is used.

traitgram

If not NULL (default), a number to be passed to funct.phylo.dist (phyloWeight; the ‘a’ parameter), causing analysis on a distance matrix reflecting both traits and phylogeny (0 –> only phylogeny, 1 –> only traits; see funct.phylo.dist). Unlike other metric wrapper functions, dissimilarity does not accept a vector of traitgram values; call the function many times to get these. This is simply because it can take so long: you're probably better off looping/apply-ing over this function yourself.

traitgram.p

A value for ‘p’ to be used in conjunction with traitgram when calling funct.phylo.dist.

ext.dist

Supply an external species-level distance matrix for use in calculations. See ‘details’ for comments on the use of distance matrices in different metric calculations.

...

additional parameters to be passed to 'metric function(s) you are calling

Details

Using square-rooted distance matrices, or distance matrices that incorporate trait information, can be an excellent thing to do, but (for the above reasons), pez won't give you an answer for metrics for which WDP thinks it makes no sense. All results from this other than comdist *will always be wrong* if you do not have an ultrametric tree and square-root (branch lengths proportional to time) and you will be warned about this. WDP strongly feels you should only be using ultrametric phylogenies in any case, but code to fix this bug is welcome.

Value

list object of metric values.

Author(s)

M.R. Helmus, Will Pearse

References

Pearse W.D., Purvis A., Cavender-Bares J. & Helmus M.R. (2014). Metrics and Models of Community Phylogenetics. In: Modern Phylogenetic Comparative Methods and Their Application in Evolutionary Biology. Springer Berlin Heidelberg, pp. 451-464.

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.

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.

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.

See Also

pez.shape pez.evenness pez.dispersion

Examples

data(laja)
data <- comparative.comm(invert.tree, river.sites, invert.traits)
## Not run: 
dissim <- pez.dissimilarity(data)

## End(Not run)