generic.metrics: Calculate any metric(s) (and compare with null distributions)

In willpearse/pez: Phylogenetics for the Environmental Sciences

Description

Allow the calculation of any metric within pez.

Usage

generic.null(data, metrics, null.model = c("taxa.labels", "richness",
  "frequency", "sample.pool", "phylogeny.pool", "independentswap",
  "trialswap", "trait.asm"), permute = 1000, comp.fun = .ses, ...)

.ses(observed, null)

.metric.null(data, metrics, null.model = c("taxa.labels", "richness",
  "frequency", "sample.pool", "phylogeny.pool", "independentswap",
  "trialswap", "trait.asm"), permute = 1000, trait = -1, ...)

generic.metrics(data, metrics, ...)

Arguments

data	data comparative.comm object
metrics	vector of functions to be calculated on data; see pez.metrics for a list of them.
null.model	one of "taxa.labels", "richness", "frequency", "sample.pool", "phylogeny.pool", "independentswap", or "independentswap". These correspond to the null models available in picante
permute	number of null permutations to perform (default 1000)
comp.fun	comparison function to compare observed values with null values. Default is .ses; this is a Standard Effect Size (obs - mean)/SEmean. You may supply your own function; it should take the observed site-metric matrix as its first argument, and a site-metric-permutation array as its second. See the internals of generic.null for an example of its use.
...	additional arguments (e.g, dist, abundance.weighted) to be passed to any metric functions (see generic.metrics for possible arguments)
observed	observed metric values in site-metric matrix (e.g., from generic.metrics)
null	null distributions (e.g., from .metric.null) in a site-metric-permutation array
trait	if using trait.asm null.model, which trait to use (as in trait.asm)

Details

generic.null Calculate metrics and compare with null distributions. Very light wrapper around the utility functions generic.null and generic.metrics (which is, itself, a very simple function!).

Value

generic.null Output from comp.fun, by default an array (site-metric-type), where type is the observed value, the mean of the null permutations, the Standard Error of that mean, the Standard Effect Size of the metric (obs-null.mean)/SE, and then the rank of the observed value in the permutations. The rank can be considered a bootstrapped p-value of significance, but remember that this is a rank: at the 95 would be significant.

.ses Vector of standard effect sizes

.metric.null site-metric-permutation array

generic.metrics site-metric matrix

Note

comp.fun can be anything; much ink has been written about the use of standard effect sizes in eco-phylogenetic analyses (e.g., Kembel 2009). That this function makes it easy for you to compute Standard Effect Sizes does not necessarily mean that you should (see Pearse et al. 2013).

Calculating null permutations on a dispersion metric makes little sense, since (by definition; see Pearse et al. 2014) a dispersion metric require the use of a null distribution to be calculated. There is nothing to stop you doing so, however! The code makes no attempt to stop you calculating null dissimilarity metrics, but I am not certain that doing so is a good idea using this code as I don't know what to do with such null models!

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

Author(s)

Will Pearse

References

Kembel S.W. (2009) Disentangling niche and neutral influences on community assembly: assessing the performance of community phylogenetic structure tests. Ecology letters, 12(9), 949-960.

Pearse W.D., Jones F.A. & Purvis A. (2013) Barro Colorado Island's phylogenetic assemblage structure across fine spatial scales and among clades of different ages. Ecology, 94(12), 2861-2872.

Examples

#Setup data
data(laja)
data <- comparative.comm(invert.tree, river.sites, invert.traits)
#Calculate some metrics
generic.metrics(data, c(.mpd, .pse))
#Compare with a trait-based null model (trait.asm)
generic.null(data, c(.mpd, .pse), "trait.asm", permute=10, trait="fish.pref")
#...be patient when running large (e.g., 1000) sets of null simulations
#You can also do this in pieces, giving even more flexibility
observed <- generic.metrics(data, c(.mpd, .pse))
#null <- .metric.null(data, c(.mpd, .pse))
#ses <- .ses(observed, null)
#...this is how everything works within generic.null
#...and, as with everything in pez, all internal functions start with a "."

willpearse/pez documentation built on June 18, 2019, 9:33 p.m.