adiv (version 1.2)

EqRao: Apportionment of Diversity

Description

Eight functions are available.

EqRS performs the first decomposition of diversity developed in Pavoine et al. (2016) and rtestEqRS can be used for the associated permutation tests.

EqRSintra performs the second decomposition of diversity developed in Pavoine et al. (2016) and rtestEqRSintra can be used for the associated permutation tests.

EqRao performs the third decomposition of diversity introduced in Pavoine et al. (2016) and rtestEqRao can be used for the associated permutation tests.

wapqe performs the apportionment of quadratic entropy (Rao 1986) and rtestwapqe associated permutation tests (Pavoine et al. 2016).

Usage

EqRS(comm, dis = NULL, structures = NULL, 
option = c("eq", "normed1", "normed2"), 
formula = c("QE", "EDI"), tol = 1e-08)
EqRSintra(comm, dis = NULL, structures = NULL, 
option = c("eq", "normed1", "normed2"), 
formula = c("QE", "EDI"), tol = 1e-08, 
metmean = c("harmonic", "arithmetic"))
EqRao(comm, dis = NULL, structures = NULL, 
option = c("eq", "normed1", "normed2"), 
formula = c("QE", "EDI"), wopt = c("even", "speciesab"), 
tol = 1e-08, metmean = c("harmonic", "arithmetic"))
wapqe(comm, dis = NULL, structures = NULL, 
formula = c("QE", "EDI"), wopt = c("even", "speciesab"), 
tol = 1e-08)
rtestEqRS(comm, dis = NULL, structures = NULL, 
formula = c("QE", "EDI"), 
option = c("normed1", "normed2", "eq"), level = 1, nrep = 99, 
alter = c("greater", "less", "two-sided"), tol = 1e-08)
rtestEqRSintra(comm, dis = NULL, structures = NULL, 
formula = c("QE", "EDI"), 
option = c("normed1", "normed2", "eq"), level = 1, 
nrep = 99, alter = c("greater", "less", "two-sided"), 
tol = 1e-08, metmean = c("harmonic", "arithmetic"))
rtestEqRao(comm, dis = NULL, structures = NULL, 
formula = c("QE", "EDI"), 
option = c("normed1", "normed2", "eq"), 
wopt = c("even", "speciesab"), level = 1, nrep = 99, 
alter = c("greater", "less", "two-sided"), tol = 1e-08, 
metmean = c("harmonic", "arithmetic"))
rtestwapqe(comm, dis = NULL, structures = NULL, 
formula = c("QE", "EDI"), wopt = c("even", "speciesab"), 
level = 1, nrep = 99, alter = c("greater", "less", "two-sided"),
tol = 1e-08)

Arguments

comm

a data frame or a matrix with communities as rows and species as columns. Entries are abundances of species within sites.

dis

either NULL or an object of class dist that contains the (functional or phylogenetic) distances among species. If NULL, the Gini-Simpson index is used.

structures

either NULL or a data frame that contains, in the jth row and the kth column, the name of the group of level k to which the jth community belongs. Communities in structures should be in the same order as in comm. See details.

option

"eq", "normed1" or "normed2" (if a vector with several codes is given, only the first one is considered). "eq" means that the diversity components are given in terms of equivalent number (E) of species, sites, regions etc. "normed1" means that the normed components of diversity will be returned with formula (1 - 1 / E) / (1 - 1 / Emax); "normed2" means that the normed components of diversity will be returned with formula (E - 1) / (Emax - 1). For Ealpha and Egamma, Emax=S (the number of species in the data set).

formula

either "QE" (default) or "EDI". See details.

wopt

either "even" (default), "speciesab", or a numeric vector. If w="speciesab", then the communities will be weighted by their sum of species' abundances. If w="even", the communities will be evenly weighted within the factors defined by the parameter structures.

tol

a tolerance threshold (a value between -tol and tol is considered equal to zero)

metmean

a character string: either "arithmetic" or "harmonic" (default).

level

a number. The number is discarded if the parameter structures is set to NULL. If structures is different from NULL then 1 means test for differences among communities, within the levels of the first factor given in parameter structures (column 1), 2 means test for differences among levels of the first factor given in parameter structures (column 1) but within levels of the second factor given in parameter structures (column 2) (if available), etc. level should thus be between 1 and 1+the number of columns in structures. See details for concrete examples.

nrep

the number of permutations.

alter

a character string specifying the alternative hypothesis, must be one of "greater" (default), "less" or "two-sided".

Value

The functions EqRS, EqRSintra, EqRao, wapqe return a data frame with each component of the selected diversity decomposition. The functions rtestEqRS, rtestEqRSintra, rtestEqRao, and rtestwapqe return a list of class randtest or krandtest (classes of package ade4).

Details

If formula = "QE", the definition of the quadratic entropy is: $$QE(\mathbf{p}_i,\mathbf{D})=\sum_{k=1}^S\sum_{l=1}^S p_{k|i}p_{k|j}d_{kl}$$ where \(\mathbf{p}_i=(p_{1|i}, ..., p_{k|i}, ..., p_{S|i})\) is the vector of relative species abundance within community i; S is the number of species; \(\mathbf{D}=(d_{kl})\) is the matrix of (phylogenetic or functional) dissimilarities among species, and \(d_{kl}\) is the (phylogenetic or functional) dissimilarity between species k and l.

If formula = "EDI", the definition of the quadratic entropy is: $$EDI(\mathbf{p}_i,\mathbf{D})=\sum_{k=1}^S\sum_{l=1}^S p_{k|i}p_{k|j}\frac{d_{kl}^2}{2}$$ EDI stands for the Euclidean Diversity Index of Champely and Chessel (2002). For example, applying EqRao with the distances dis=mydis and formula=QE corresponds to applying it with dis=sqrt(2*mydis) and formula=EDI.

Parameter level permits to choose the component of beta diversity that will be tested for significance.

Examples are given below:

Scenario 1: Imagine that structures is NULL, then we only have a set of communities, species within them and a matrix of (functional or phylogenetic) dissimilarities among species. Then there is only one level of beta diversity which represents the average dissimilarities among communities. The functions rtestEqRS, rtestEqRSintra, rtestEqRao, and rtestwapqe will always, in that case, test for the significance of the dissimilarities among communities (whatever the value given to parameter level).

Scenario 2: Imagine that structures is a data frame with sites as rows and only one column representing how sites are distributed among regions. Then, there are two levels of beta diversity: beta1 diversity represents the (functional or phylogenetic) dissimilarities among sites within regions; and beta2 diversity represents the (functional or phylogenetic) dissimilarities among regions. If level = 1 then functions rtestEqRS, rtestEqRSintra, rtestEqRao, and rtestwapqe will test for the significance of the dissimilarities among sites within regions (beta1 diversity); in contrast, if level = 2 functions rtestEqRS, rtestEqRSintra, rtestEqRao, and rtestwapqe will test for the significance of the dissimilarities among regions (beta2 diversity). As there is only one column in parameter structures and thus only two levels of diversity, level cannot be higher than 2.

Scenario 3: Imagine now that parameter comm contains quadrats as rows and species as columns and that structures is a data frame with quadrats as rows and three columns representing how quadrats are organized in three nested factors: hamlets, towns, and counties. Then there would be four levels of beta diversity: beta1 diversity represents the (functional or phylogenetic) dissimilarities among quadrats within hamlets, towns, and counties; beta2 diversity represents the dissimilarities among hamlets within towns and counties; beta3 diversity represents the dissimilarities among towns within counties; and beta4 diversity represents the dissimilarities among counties. If level = 1 then functions rtestEqRS, rtestEqRSintra, rtestEqRao, and rtestwapqe will test for the significance of the dissimilarities among quadrats within hamlets, towns, and counties (beta1 diversity); if level = 2 functions rtestEqRS, rtestEqRSintra, rtestEqRao, and rtestwapqe will test for the significance of the dissimilarities among hamlets within towns and regions (beta2 diversity); if level = 3 functions rtestEqRS, rtestEqRSintra, rtestEqRao, and rtestwapqe will test for the significance of the dissimilarities among towns within regions (beta3 diversity); if level = 4 functions rtestEqRS, rtestEqRSintra, rtestEqRao, and rtestwapqe will test for the significance of the dissimilarities among regions (beta4 diversity). As there are only three columns in parameter structures and thus only four levels of diversity, level cannot be higher than 4. Test for level=1 is performed by permuting the abundances of each species across quadrats but within hamlets, towns, and counties. Test for level=2 is performed by permuting the quadrats among hamlets within towns and counties. Test for level=3 is performed by permuting the hamlets among towns within counties. Test for level=4 is performed by permuting the towns among counties.

Other permutation schemes will be added in the future.

References

Pavoine, S., Marcon, E., Ricotta, C. (2016) "Equivalent numbers" for species, phylogenetic, or functional diversity in a nested hierarchy of multiple scales. Methods in Ecology and Evolution, 7, 1152--1163.

Champely, S. and Chessel, D. (2002) Measuring biological diversity using Euclideanmetrics. Environmental and Ecological Statistics, 9, 167--177.

Rao, C.R. (1986) Rao's axiomatization of diversity measures. In: Encyclopedia of Statistical Sciences. Vol. 7 (eds S. Kotz and N.L. Johnson), pp. 614--617. New York: Wiley and Sons.

Examples

# NOT RUN {
data(macroloire, package="ade4")

# Taxonomic dissimilarities among species:
dTaxo <- dist.taxo(macroloire$taxo)^2/2
dTaxo <- dTaxo/max(dTaxo)
# Size-based dissimilarities among species
dSize <- dist.prop(macroloire$traits[ ,1:4], method = 2)
# Dissimilarities among species in terms of feeding categories
dFeed <- dist.prop(macroloire$traits[ ,5:11], method = 2)
# Dissimilarities among species in terms of 
# both size and feeding categories
dSF <- (dSize+dFeed)/2

# Table with sites as rows (stations), 
# species as columns and abundances as entries
ab <- as.data.frame(t(macroloire$fau))
# Table with sites as rows and one column only. 
# Entries indicate the geological region associated 
# with each site
stru <- macroloire$envir["Morphoregion"]

EqRao(ab, , stru, option="eq")
EqRao(ab, dTaxo, stru, formula = "QE", option="eq")
EqRao(ab, dSize, stru, formula = "QE", option="eq")
EqRao(ab, dFeed, stru, formula = "QE", option="eq")
EqRao(ab, dSF, stru, formula = "QE", option="eq")

EqRao(ab, , stru, option="normed2")
EqRao(ab, dTaxo, stru, formula = "QE", option="normed2")
EqRao(ab, dSize, stru, formula = "QE", option="normed2")
EqRao(ab, dFeed, stru, formula = "QE", option="normed2")
EqRao(ab, dSF, stru, formula = "QE", option="normed2")

# }
# NOT RUN {
# Tests for dissimilarities among sites within regions:

rb1_GS <- rtestEqRao(ab, , stru, level=1, nrep=999, option="normed2")
rb1_GS
plot(rb1_GS)
rb1_Taxo <- rtestEqRao(ab, dTaxo, stru, formula = "QE", 
level=1, nrep=999, option="normed2")
rb1_Taxo
plot(rb1_Taxo)
rb1_Size <- rtestEqRao(ab, dSize, stru, formula = "QE", 
level=1, nrep=999, option="normed2")
rb1_Size
plot(rb1_Size)
rb1_Feed <- rtestEqRao(ab, dFeed, stru, formula = "QE", 
level=1, nrep=999, option="normed2")
rb1_Feed
plot(rb1_Feed)
rb1_SF <- rtestEqRao(ab, dSF, stru, formula = "QE", 
level=1, nrep=999, option="normed2")
rb1_SF
plot(rb1_SF)

# Tests for dissimilarities among regions:

r2_GS <- rtestEqRao(ab, , stru, level=2, nrep=999, option="normed2")
r2_GS
plot(r2_GS)
r2_Taxo <- rtestEqRao(ab, dTaxo, stru, formula = "QE", 
level=2, nrep=999, option="normed2")
r2_Taxo
plot(r2_Taxo)
r2_Size <- rtestEqRao(ab, dSize, stru, formula = "QE", 
level=2, nrep=999, option="normed2", w="even")
r2_Size
plot(r2_Size)
r2_Feed <- rtestEqRao(ab, dFeed, stru, formula = "QE", 
level=2, nrep=999, option="normed2", w="even")
r2_Feed
plot(r2_Feed)
r2_SF <- rtestEqRao(ab, dSF, stru, formula = "QE", 
level=2, nrep=999, option="normed2", w="even")
r2_SF
plot(r2_SF)
# }