pez (version 1.2-0)

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

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)

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

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!).

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

# NOT RUN {
#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 "."
# }