multipatt {indicspecies}

Multi-level pattern analysis

Description

This function studies the association between species patterns and combinations of groups of sites.

Usage

multipatt(
  x,
  cluster,
  func = "IndVal.g",
  duleg = FALSE,
  restcomb = NULL,
  min.order = 1,
  max.order = NULL,
  control = how(),
  permutations = NULL,
  print.perm = FALSE
)

Arguments

x

Community data table

cluster

A vector representing a partition of sites

func

Species-site group association function. Four values are accepted "IndVal", "IndVal.g", "r" and "r.g" (lowercase values are also accepted).

duleg

If TRUE, site group combinations are not considered, only the original site groups, like in Dufrêne & Legendre (1997). Internally, duleg = TRUE equals max.order = 1.

restcomb

A vector of integer values used to restrict the combinations of site groups to those with ecological sense according to the analyst. The default NULL indicates that all combinations are used. If duleg=TRUE this argument is ignored.

min.order

An integer indicating the minimum order of site group combinations (by default max.order=1 for singletons). Cannot be larger than max.order.

max.order

An integer indicating the maximum order of site group combinations to be considered: max.order=1 for singletons, max.order=2 for pairs, max.order=3 for triplets... As restcomb, this parameter provide a way to restrict the site group combinations that make ecological sense. By default all possible site group combinations are considered. If max.order=1 then the function will behave as if duleg=TRUE.

control

A list of control values describing properties of the permutation design, as returned by a call to how.

permutations

A custom matrix of permutations, to be used if control = NULL, with permutations in rows and site indices in columns

print.perm

If TRUE, prints permutation numbers after each set of 100 permutations.

Details

This function creates combinations of the input clusters and compares each combination with the species in the input matrix x. For each species it chooses the combination with a highest association value. Best matching patterns are tested for statistical significance of the associations. Four association indices are possible (some less than for strassoc): "IndVal", "IndVal.g", "r" and "r.g". Indicator value indices will return the pattern that better matches the species observed pattern, whereas correlation indices will return the pattern that creates a highest inside/outside difference. Details are given in De Cáceres et al. (2010). The user can restrict the combinations in three ways: (1) by using duleg=TRUE, which leads to consider single site-groups only; (2) by setting the minimum and maximum order of combinations using min.order and max.order; or (3) by using restcomb to restrict combinations at will. In order to carry out the third way, values in restcomb must be the indices of combinations that appear in the column index of object sign (see below).

Complex permutation designs are allowed through the function how from package "permute". If those are not enough, the user can set control = NULL and specify a custom matrix of permutations to test with parameter permutations.

Value

An object of class multipatt with:

func

The name of the function used.

comb

A matrix describing all the combinations studied.

str

A matrix the association strength for all combinations studied.

A

If func = "IndVal" (or func = "IndVal.g") a matrix whose values are the "A" (or "A.g") component of indicator values. Otherwise this element is left as NULL.

B

If func = "IndVal" (or func = "IndVal.g") a matrix whose values are the "B" component of indicator values. Otherwise this element is left as NULL.

sign

Data table with results of the best matching pattern, the association value and the degree of statistical significance of the association (i.e. p-values from permutation test). Note that p-values are not corrected for multiple testing.

Note

This function gives the same results as function indval in package "labdsv" when used setting func="IndVal.g" and duleg=TRUE, excepting the fact that the square root IndVal values is returned instead of the original IndVal.

Author(s)

Miquel De Cáceres Ainsa, EMF-CREAF

Florian Jansen, Institute of Botany and Landscape Ecology, Ernst-Moritz-Arndt-University

References

De Cáceres, M. and Legendre, P. 2009. Associations between species and groups of sites: indices and statistical inference. Ecology 90(12): 3566-3574.

De Cáceres, M., Legendre, P., Moretti, M. 2010. Improving indicator species analysis by combining groups of sites. Oikos 119(10): 1674-1684.

Dufrêne, M. and P. Legendre. 1997. Species assemblages and indicator species: The need for a flexible asymetrical approach. Ecological Monographs 67:345-366.

See Also

summary.multipatt, strassoc, signassoc, how

Examples

library(stats)

data(wetland) ## Loads species data

wetkm <- kmeans(wetland, centers=3) ## Creates three clusters using kmeans

## Runs the combination analysis using IndVal.g as statistic
wetpt <- multipatt(wetland, wetkm$cluster, control = how(nperm=999)) 

## Lists those species with significant association to one combination
summary(wetpt) 

## Lists those species with significant association to one combination, 
## including indval components.
summary(wetpt, indvalcomp=TRUE)