Package 'entropart'

Description

Functions to calculate alpha, beta and gamma diversity of communities, including phylogenetic and functional diversity.

Estimation-bias corrections are available.

Details

In the entropart package, individuals of different "species" are counted in several "communities" which may (or not) be agregated to define a "metacommunity". In the metacommunity, the probability to find a species in the weighted average of probabilities in communities. This is a naming convention, which may correspond to plots in a forest inventory or any data organized the same way.

Basic functions allow computing diversity of a community. Data is simply a vector of probabilities (summing up to 1) or of abundances (integer values that are numbers of individuals). Calculate entropy with functions such as Tsallis, Shannon, Simpson, Hurlbert or GenSimpson and explicit diversity (i.e. effective number of species) with Diversity and others. By default, the best available estimator of diversity will be used, according to the data.

Communities can be simulated by rCommunity, explicitely declared as a species distribution (as.AbdVector or as.ProbaVector), and plotted.

Phylogenetic entropy and diversity can be calculated if a phylogenetic (or functional), ultrametric tree is provided. See PhyloEntropy, Rao for examples of entropy and PhyloDiversity to calculate phylodiversity, with the state-of-the-art estimation-bias correction. Similarity-based diversity is calculated with Dqz, based on a similarity matrix.

The simplest way to import data is to organize it into two text files. The first file should contain abundance data: the first column named Species for species names, and a column for each community.

The second file should contain the community weights in two columns. The first one, named Communities should contain their names and the second one, named Weights, their weights.

Files can be read and data imported by code such as:

Abundances <- read.csv(file="Abundances.csv", row.names = 1)
Weights <- read.csv(file="Weights.csv")
MC <- MetaCommunity(Abundances, Weights)

The last line of the code calls the MetaCommunity function to create an object that will be used by all metacommunity functions, such as DivPart (to partition diversity), DivEst (to partition diversity and calculate confidence interval of its estimation) or DivProfile (to compute diversity profiles).

A full documentation is available in the vignette. Type: vignette("entropart"). A quick introuction is in vignette("introduction", "entropart").

Author(s)

Eric Marcon, Bruno Herault

References

Grabchak, M., Marcon, E., Lang, G., and Zhang, Z. (2017). The Generalized Simpson's Entropy is a Measure of Biodiversity. Plos One, 12(3): e0173305.

Marcon, E. (2015) Practical Estimation of Diversity from Abundance Data. HAL 01212435: 1-27.

Marcon, E. and Herault, B. (2015). entropart: An R Package to Measure and Partition Diversity. Journal of Statistical Software, 67(8): 1-26.

Marcon, E., Herault, B. (2015). Decomposing Phylodiversity. Methods in Ecology and Evolution 6(3): 333-339.

Marcon, E., Herault, B., Baraloto, C. and Lang, G. (2012). The Decomposition of Shannon's Entropy and a Confidence Interval for Beta Diversity. Oikos 121(4): 516-522.

Marcon, E., Scotti, I., Herault, B., Rossi, V. and Lang G. (2014). Generalization of the partitioning of Shannon diversity. PLOS One 9(3): e90289.

Marcon, E., Zhang, Z. and Herault, B. (2014). The decomposition of similarity-based diversity and its bias correction. HAL hal-00989454(version 3).

Description

Counts the number of species observed the same number of times.

Usage

AbdFreqCount(Ns, Level = NULL, PCorrection="Chao2015", Unveiling="geom", 
  RCorrection="Rarefy", CheckArguments = TRUE)

Arguments

Details

The Abundance Frequency Count (Chao et al., 2015) is the number of species observed each number of times.

It is a way to summarize the species distribution.

It can be estimated at a specified level of interpolation or extrapolation. Extrapolation relies on the estimation of the estimation of the asymptotic distribution of the community by as.ProbaVector and eq. (5) of Chao et al. (2014).

Value

A two-column matrix. The first column contains the number of observations, the second one the number of species observed this number of times.

References

Chao, A., Gotelli, N. J., Hsieh, T. C., Sander, E. L., Ma, K. H., Colwell, R. K., Ellison, A. M (2014). Rarefaction and extrapolation with Hill numbers: A framework for sampling and estimation in species diversity studies. Ecological Monographs, 84(1): 45-67.

Chao, A., Hsieh, T. C., Chazdon, R. L., Colwell, R. K., Gotelli, N. J. (2015) Unveiling the Species-Rank Abundance Distribution by Generalizing Good-Turing Sample Coverage Theory. Ecology 96(5): 1189-1201.

See Also

PhyloEntropy, ChaoPD

Examples

# Load Paracou data (number of trees per species in two 1-ha plot of a tropical forest
#      and their taxonomy)
data(Paracou618)
# Ns is the vector of abundances of the first plot
Ns <- Paracou618.MC$Nsi[, 1]

# Return the abundance frequency count
(AbdFreqCount(Ns) -> afc)
plot(afc, xlab="Number of observations", ylab="Number of species")
lines(afc)

Description

Diversity and Entropy Accumulation Curves represent the accumulation of entropy with respect to the sample size.

Usage

as.AccumCurve(x, y, low = NULL, high = NULL)
is.AccumCurve(x)
EntAC(Ns, q = 0, n.seq = seq_len(sum(Ns)), PCorrection="Chao2015", Unveiling="geom",
  RCorrection="Rarefy", NumberOfSimulations = 0, Alpha = 0.05, 
  ShowProgressBar = TRUE, CheckArguments = TRUE)
DivAC(Ns, q = 0, n.seq = seq_len(sum(Ns)), PCorrection="Chao2015", Unveiling="geom",
  RCorrection="Rarefy", NumberOfSimulations = 0, Alpha = 0.05, 
  ShowProgressBar = TRUE, CheckArguments = TRUE)
## S3 method for class 'AccumCurve'
plot(x, ..., main = NULL, 
         xlab = "Sample Size", ylab = NULL, ylim = NULL,
         LineWidth = 2, ShadeColor = "grey75", BorderColor = "red")
## S3 method for class 'AccumCurve'
autoplot(object, ..., main = NULL, 
         xlab = "Sample Size", ylab = NULL, 
         ShadeColor = "grey75", alpha = 0.3, BorderColor = "red",
         col = ggplot2::GeomLine$default_aes$colour,
         lty = ggplot2::GeomLine$default_aes$linetype,
         lwd = ggplot2::GeomLine$default_aes$size)

Arguments

Details

DivAC or EntAC estimate the diversity or entropy accumulation curve of a distribution. See Tsallis for details about the computation of entropy at each level of interpolation and extrapolation. In accumulation curves, extrapolation if done by estimating the asymptotic distribution of the community and estimating entropy at different levels by interpolation. The asymptotic richess is adjusted so that the extrapolated part of the accumulation joins the observed value at the sample size.

AccumCurve objects include EntAC and DivAC objects for entropy and diversity accumulation. They generalize the classical Species Accumulation Curves (SAC) which are diversity accumulation of order $q=0$.

as.AccumCurve transforms two vectors (where x is the sammple size and y the accumulation) into an object of class AccumCurve.

AccumCurve objects can be plotted with either plot or autoplot methods.

Value

A DivAC or an EntAC object. Both are AccumCurve objects, which are a list:

Attibutes "Size" and "Value" contain the actual sample size and the corresponding diversity or entropy.

AccumCurve objects can be summarized and plotted.

References

Chao, A., Gotelli, N. J., Hsieh, T. C., Sander, E. L., Ma, K. H., Colwell, R. K., Ellison, A. M (2014). Rarefaction and extrapolation with Hill numbers: A framework for sampling and estimation in species diversity studies. Ecological Monographs, 84(1): 45-67.

See Also

Tsallis, Diversity

Examples

# Load Paracou data (number of trees per species in two 1-ha plot of a tropical forest)
data(Paracou618)
# Ns is the total number of trees per species
Ns <- as.AbdVector(Paracou618.MC$Ns)
# Accumulation curve of Simpson's diversity
autoplot(DivAC(Ns, q=2))

Description

Calculates the phylogenetic diversity of order $q$ of a probability vector.

Usage

AllenH(Ps, q = 1, PhyloTree, Normalize = TRUE, Prune = FALSE, CheckArguments = TRUE)

Arguments

Details

The phylogenetic entropy is calculated following Allen et al. (2009) for order $q=1$ and Leinster and Cobold (2011) for other orders.The result is identical to the total entropy calculated by PhyloEntropy but it is much faster. A single value is returned instead of a PhyloEntropy object, and no bias correction is available.

The Normalize argument allows normalizing entropy by the height of the tree, similarly to ChaoPD.

Diversity can be calculated for non ultrametric trees following Leinster and Cobold (2011) even though the meaning of the result is not so clear.

Value

A named number equal the entropy of the community. The name is "None" to recall that no bias correction is available.

References

Allen, B., Kon, M. and Bar-Yam, Y. (2009). A New Phylogenetic Diversity Measure Generalizing the Shannon Index and Its Application to Phyllostomid Bats. American Naturalist 174(2): 236-243.

Leinster, T. and Cobbold, C. (2011). Measuring diversity: the importance of species similarity. Ecology 93(3): 477-489.

See Also

PhyloEntropy, ChaoPD

Examples

# Load Paracou data (number of trees per species in two 1-ha plot of a tropical forest
#      and their taxonomy)
data(Paracou618)
# Ps is the vector of probabilities
Ps <- as.ProbaVector(Paracou618.MC$Ns)

# Calculate the phylogenetic Shannon diversity of the plot
AllenH(Ps, 1, Paracou618.Taxonomy, Normalize=TRUE)

# Calculate it using PhyloEntropy: more powerful but much slower is the tree has many periods
PhyloEntropy(Ps, 1, Paracou618.Taxonomy, Normalize=TRUE) -> phyE
summary(phyE)

Description

Calculates the eeduced-bias total alpha diversity of order $q$ of communities.

Usage

AlphaDiversity(MC, q = 1, Correction = "Best", Tree = NULL, Normalize = TRUE, 
  Z = NULL, CheckArguments = TRUE)

Arguments

Details

Entropy is calculated by AlphaEntropy and transformed into diversity.

Value

An MCdiversity object containing diversity values of each community and of the metacommunity.

References

Marcon, E., Scotti, I., Herault, B., Rossi, V. and Lang, G. (2014). Generalization of the partitioning of Shannon diversity. PLOS One 9(3): e90289.

Marcon, E., Herault, B. (2015). Decomposing Phylodiversity. Methods in Ecology and Evolution 6(3): 333-339.

Marcon, E., Zhang, Z. and Herault, B. (2014). The decomposition of similarity-based diversity and its bias correction. HAL hal-00989454(version 3).

See Also

AlphaEntropy

Examples

# Load Paracou data (number of trees per species in two 1-ha plot of a tropical forest)
data(Paracou618)
# Calculate Simpson alpha diversity
summary(AlphaDiversity(Paracou618.MC, 2))
# Compare without correction
summary(AlphaDiversity(Paracou618.MC, 2, Correction = "None"))
# Estimate phylogenetic Simpson alpha diversity
summary(AlphaDiversity(Paracou618.MC, 2, Tree = Paracou618.Taxonomy) -> e)
plot(e)

Description

Calculates the reduced-bias total alpha entropy of order $q$ of communities.

Usage

AlphaEntropy(MC, q = 1, Correction = "Best", Tree = NULL, Normalize = TRUE,
  Z = NULL, CheckArguments = TRUE)

Arguments

Details

If Tree is not NULL, then phylogenetic entropy is calculated by bcPhyloEntropy; else, if Z is not NULL, then similarity-based entropy is calculated by bcHqz; else, neutral entropy is calculated by bcTsallis.

The alpha entropy of each community is calculated and summed according to community weights.

The possible corrections are detailed in Tsallis.

Value

An MCentropy object containing entropy values of each community and of the metacommunity.

References

Marcon, E., Scotti, I., Herault, B., Rossi, V. and Lang, G. (2014). Generalization of the partitioning of Shannon diversity. PLOS One 9(3): e90289.

Marcon, E., Herault, B. (2015). Decomposing Phylodiversity. Methods in Ecology and Evolution 6(3): 333-339.

Marcon, E., Zhang, Z. and Herault, B. (2014). The decomposition of similarity-based diversity and its bias correction. HAL hal-00989454(version 3).

See Also

bcTsallis

Examples

# Load Paracou data (number of trees per species in two 1-ha plot of a tropical forest)
data(Paracou618)
# Calculate Simpson alpha entropy
summary(AlphaEntropy(Paracou618.MC, 2))
# Compare without correction
summary(AlphaEntropy(Paracou618.MC, 2, Correction = "None"))
# Estimate phylogenetic Simpson alpha entropy
summary(AlphaEntropy(Paracou618.MC, 2, Tree = Paracou618.Taxonomy) -> e)
plot(e)

Description

Calculates the reduced-bias beta diversity of order $q$ between communities.

Usage

BetaDiversity(MC, q = 1, Correction = "Best", Tree = NULL, Normalize = TRUE, 
  Z = NULL, CheckArguments = TRUE)

Arguments

Details

Entropy is calculated by BetaEntropy and transformed into diversity.

Diversity values of communities are not defined: community entropies are averaged to obtain the metacommunity entropy wich is transformed into diversity (Marcon et al., 2014).

Value

An MCdiversity object containing diversity value of the metacommunity.

References

Marcon, E., Scotti, I., Herault, B., Rossi, V. and Lang, G. (2014). Generalization of the partitioning of Shannon diversity. PLOS One 9(3): e90289.

Marcon, E., Herault, B. (2015). Decomposing Phylodiversity. Methods in Ecology and Evolution 6(3): 333-339.

Marcon, E., Zhang, Z. and Herault, B. (2014). The decomposition of similarity-based diversity and its bias correction. HAL hal-00989454(version 3).

See Also

BetaEntropy

Examples

# Load Paracou data (number of trees per species in two 1-ha plot of a tropical forest)
data(Paracou618)
# Estimate Shannon beta diversity
summary(BetaDiversity(Paracou618.MC, 1))
# Compare without correction
summary(BetaDiversity(Paracou618.MC, 1, Correction = "None"))
# Estimate phylogenetic Shannon beta diversity
summary(BetaDiversity(Paracou618.MC, 1, Tree = Paracou618.Taxonomy) -> e)

Description

Calculates the reduced-bias beta entropy of order $q$ between communities.

Usage

BetaEntropy(MC, q = 1, Correction = "Best", Tree = NULL, Normalize = TRUE, 
  Z = NULL, CheckArguments = TRUE)

Arguments

Details

If Tree is not NULL, then phylogenetic entropy is calculated by bcPhyloBetaEntropy; else, if Z is not NULL, then similarity-based entropy is calculated by bcHqzBeta; else, neutral entropy is calculated by bcTsallisBeta.

The reduced-bias beta entropy of each community is calculated and summed according to community weights.

Note that beta entropy is related to alpha entropy (if $q$ is not 1) and cannot be compared accross communities (Jost, 2007). Do rather calculate the BetaDiversity of the metacommunity.

Value

An MCentropy object containing entropy values of each community and of the metacommunity.

References

Marcon, E., Scotti, I., Herault, B., Rossi, V. and Lang, G. (2014). Generalization of the partitioning of Shannon diversity. PLOS One 9(3): e90289.

Marcon, E., Herault, B. (2015). Decomposing Phylodiversity. Methods in Ecology and Evolution 6(3): 333-339.

Marcon, E., Zhang, Z. and Herault, B. (2014). The decomposition of similarity-based diversity and its bias correction. HAL hal-00989454(version 3).

See Also

bcTsallisBeta, BetaDiversity

Examples

# Load Paracou data (number of trees per species in two 1-ha plot of a tropical forest)
data(Paracou618)
# Estimate Shannon beta entropy
summary(BetaEntropy(Paracou618.MC, 1))
# Compare without correction
summary(BetaEntropy(Paracou618.MC, 1, Correction = "None"))
# Estimate phylogenetic Shannon beta entropy
summary(BetaEntropy(Paracou618.MC, 1, Tree = Paracou618.Taxonomy) -> e)
plot(e)

Description

Calculates the phylogenetic diversity of order $q$ of a probability vector.

Usage

ChaoPD(Ps, q = 1, PhyloTree, Normalize = TRUE, Prune = FALSE, CheckArguments = TRUE)

Arguments

Details

The phylogenetic diversity is calculated following Chao et al. (2010). The result is identical to the total diversity calculated by PhyloDiversity but it is much faster. A single value is returned instead of a PhyloDiversity object, and no bias correction is available.

The Normalize arguments allows calculating either $^{q}\bar{D}(T)$ (if TRUE) or $^{q}PD(T)$ if FALSE.

Diversity can be calculated for non ultrametric trees following Chao et al. (2010) even though the meaning of the result is not so clear (Leinster and Cobold, 2011).

Value

A named number equal the diversity of the community. The name is "None" to recall that no bias correction is available.

References

Chao, A., Chiu, C.-H. and Jost, L. (2010). Phylogenetic diversity measures based on Hill numbers. Philosophical Transactions of the Royal Society B 365(1558): 3599-609.

Leinster, T. and Cobbold, C. (2011). Measuring diversity: the importance of species similarity. Ecology 93(3): 477-489.

See Also

PhyloDiversity, AllenH

Examples

# Load Paracou data (number of trees per species in two 1-ha plot of a tropical forest
#      and their taxonomy)
data(Paracou618)
# Ps is the vector of probabilities
Ps <- Paracou618.MC$Ps

# Calculate the phylogenetic Simpson diversity of the plot
(ChaoPD(Paracou618.MC$Ps, 2, Paracou618.Taxonomy, Normalize=TRUE))

# Calculate it using PhyloDiversity
# (more powerful but much slower if the tree has many periods)
PhyloDiversity(Paracou618.MC$Ps, 2, Paracou618.Taxonomy, Normalize=TRUE) -> phyD
summary(phyD)

Description

Calculates the diversity or entropy profile of a community, applying a community function to a vector of orders.

Usage

CommunityProfile(FUN, NorP, q.seq = seq(0, 2, 0.1), 
    NumberOfSimulations = 0, Alpha = 0.05, BootstrapMethod = "Chao2015", 
    size = 1, ..., ShowProgressBar = TRUE, CheckArguments = TRUE)
as.CommunityProfile(x, y, low = NULL, high = NULL, mid = NULL)
is.CommunityProfile(x)
## S3 method for class 'CommunityProfile'
plot(x, ..., main = NULL, 
          xlab = "Order of Diversity", ylab = "Diversity", ylim = NULL,
          LineWidth = 2, ShadeColor = "grey75", BorderColor = "red")
## S3 method for class 'CommunityProfile'
autoplot(object, ..., main = NULL, 
          xlab = "Order of Diversity", ylab = "Diversity",
          ShadeColor = "grey75", alpha = 0.3, BorderColor = "red",
          col = ggplot2::GeomLine$default_aes$colour,
          lty = ggplot2::GeomLine$default_aes$linetype,
          lwd = ggplot2::GeomLine$default_aes$size)
CEnvelope(Profile, LineWidth = 2, ShadeColor = "grey75", BorderColor = "red", ...)

Arguments

Details

The function CommunityProfile is used to calculate diversity or entropy profiles based on community functions such as Tsallis or ChaoPD. The first two arguments of the function must be a probability or abundance vector and a number ($q$). Additional arguments cannot be checked. Unexpected results may be returned if FUN is not used properly.

If NumberOfSimulations is greater than 0, a bootstrap confidence interval is produced by simulating communities with rCommunity and calculating their profiles. The size of those communities may be that of the actual community or specified by size. Simulating communities implies a downward bias in the estimation: rare species of the actual community may have abundance zero in simulated communities. Simulated diversity values are recentered if 'size = 1' so that their mean is that of the actual community. Else, it is assumed that the bias is of interest and must not be corrected.

CommunityProfile objects can be plotted. They can also be added to the current plot by CEnvelope.

Value

A CommunityProfile, which is a list:

Author(s)

Eric Marcon <[email protected]>, Bruno Herault <[email protected]>

Examples

# Load Paracou data (number of trees per species in two 1-ha plot of a tropical forest)
data(Paracou618)
# Plot diversity estimated without bias correction
plot(CommunityProfile(Diversity, Paracou618.MC$Ps, seq(0, 2, 0.2)), 
lty=3, ylim=c(50, 350))
# Estimate diversity, with a condidence envelope 
# (only 10 simulations to save time, should be 1000)
Profile <- CommunityProfile(Diversity, as.AbdVector(Paracou618.MC$Ns), 
		  seq(0, 2, 0.2), Correction="UnveilJ", NumberOfSimulations=10)
# Complete the plot, and add the legend
CEnvelope(Profile, main="Paracou Plots Diversity")
legend("topright", c("Bias Corrected", "Biased"), lty=c(1,3), inset=0.01)

# Advanced use with beta-diversity functions :
# Profile of the beta entropy of the first community of Paracou618.
# Observed and expected probabilities are bound into a 2-column matrix
# An intermediate function is necessary to separate them before calling TsallisBeta
# The CheckArguments is mandatory but does not need to be set: CommunityProfile() sets it to FALSE
CommunityProfile(function(PandPexp, q, CheckArguments) 
  {TsallisBeta(PandPexp[, 1], PandPexp[, 2], q)}, 
  NorP=cbind(Paracou618.MC$Psi[, 1], Paracou618.MC$Ps), q.seq=seq(0, 2, 0.2))

Description

"Coverage" calculates an estimator of the sample coverage of a community described by its abundance vector. "Coverage2Size" estimates the sample size corresponding to the chosen sample coverage.

Usage

Coverage(Ns, Estimator = "Best", Level = NULL, CheckArguments = TRUE)
Coverage2Size(Ns, SampleCoverage, CheckArguments = TRUE)

Arguments

Details

The sample coverage $C$ of a community is the total probability of occurence of the species observed in the sample. $1-C$ is the probability for an individual of the whole community to belong to a species that has not been sampled.

The historical estimator is due to Turing (Good, 1953). It only relies on singletons (species observed only once). Chao's (Chao and Shen, 2010) estimator uses doubletons too and Zhang-Huang's (Chao et al., 1988; Zhang and Huang, 2007) uses the whole distribution.

If Level is not null, the sample coverage is interpolated or extrapolated. Interpolation by the Good estimator relies on the equality between sampling deficit and the generalized Simpson entropy (Good, 1953). The Chao (2014) estimator allows extrapolation, reliable up a level equal to the double size of the sample.

Value

"Coverage" returns a named number equal to the calculated sample coverage. The name is that of the estimator used. "Coverage2Size" returns a number equal to the sample size corresponding to the chosen sample coverage.

References

Chao, A., Lee, S.-M. and Chen, T.-C. (1988). A generalized Good's nonparametric coverage estimator. Chinese Journal of Mathematics 16: 189-199.

Chao, A. and Shen, T.-J. (2010). Program SPADE: Species Prediction And Diversity Estimation. Program and user's guide. CARE, Hsin-Chu, Taiwan.

Chao, A., Gotelli, N. J., Hsieh, T. C., Sander, E. L., Ma, K. H., Colwell, R. K., Ellison, A. M (2014). Rarefaction and extrapolation with Hill numbers: A framework for sampling and estimation in species diversity studies. Ecological Monographs, 84(1): 45-67.

Good, I. J. (1953). On the Population Frequency of Species and the Estimation of Population Parameters. Biometrika 40(3/4): 237-264.

Zhang, Z. and Huang, H. (2007). Turing's formula revisited. Journal of Quantitative Linguistics 14(2-3): 222-241.

Examples

# Load Paracou data (number of trees per species in two 1-ha plot of a tropical forest)
data(Paracou618)
# Ns is the vector of abundances of the metacommunity
Ns <- Paracou618.MC$Ns
# Calculate the sample coverage of the metacommunity
Coverage(Ns)    # Stored in Paracou618.SampleCoverage

Description

Calculates the HCDT (generalized) diversity of order $q$ of a probability vector.

Usage

Diversity(NorP, q = 1, ...)
bcDiversity(Ns, q = 1, Correction = "Best", CheckArguments = TRUE)
## S3 method for class 'ProbaVector'
Diversity(NorP, q = 1, ..., 
  CheckArguments = TRUE, Ps = NULL)
## S3 method for class 'AbdVector'
Diversity(NorP, q = 1, Correction = "Best", Level = NULL,
  PCorrection="Chao2015", Unveiling="geom", RCorrection="Rarefy", ...,
  CheckArguments = TRUE, Ns = NULL)
## S3 method for class 'integer'
Diversity(NorP, q = 1, Correction = "Best", Level = NULL,
  PCorrection="Chao2015", Unveiling="geom", RCorrection="Rarefy", ..., 
  CheckArguments = TRUE, Ns = NULL)
## S3 method for class 'numeric'
Diversity(NorP, q = 1, Correction = "Best", Level = NULL,
  PCorrection="Chao2015", Unveiling="geom", RCorrection="Rarefy", ..., 
  CheckArguments = TRUE, Ps = NULL, Ns = NULL)

Arguments

Details

Diversity calls Tsallis to calculate entropy and transforms it into diversity by calculating its deformed exponential.

Bias correction requires the number of individuals to estimate sample Coverage. See Tsallis for details.

The functions are designed to be used as simply as possible. Diversity is a generic method. If its first argument is an abundance vector, an integer vector or a numeric vector which does not sum to 1, the bias corrected function bcDiversity is called.

Diversity can be estimated at a specified level of interpolation or extrapolation, either a chosen sample size or sample coverage (Chao et al., 2014), rather than its asymptotic value. See Tsallis for details.

Value

A named number equal to the calculated diversity. The name is that of the bias correction used.

References

Chao, A., Gotelli, N. J., Hsieh, T. C., Sander, E. L., Ma, K. H., Colwell, R. K., Ellison, A. M (2014). Rarefaction and extrapolation with Hill numbers: A framework for sampling and estimation in species diversity studies. Ecological Monographs, 84(1): 45-67.

Marcon, E., Scotti, I., Herault, B., Rossi, V. and Lang, G. (2014). Generalization of the partitioning of Shannon diversity. PLOS One 9(3): e90289.

See Also

Tsallis, expq, AbdVector, ProbaVector

Examples

# Load Paracou data (number of trees per species in two 1-ha plot of a tropical forest)
data(Paracou618)
# Ns is the total number of trees per species
Ns <- as.AbdVector(Paracou618.MC$Ns)
# Species probabilities
Ps <- as.ProbaVector(Paracou618.MC$Ns)
# Whittaker plot
plot(Ns)
# Calculate diversity of order 1, i.e. Shannon's diversity
Diversity(Ps, q=1)
# Calculate it with estimation bias correction (asymptotic estimator)
Diversity(Ns, q=1)
# Extrapolate it up to 99.9% sample coverage (close to the asymptotic estimator)
Diversity(Ns, q=1, Level=0.999)
# Rarefy it to half the sample size
Diversity(Ns, q=1, Level=sum(Ns)/2)

Description

Estimates diversity of a metacommunity.

Usage

DivEst(q = 0, MC, Biased = TRUE, Correction = "Best", Tree = NULL, 
  Normalize = TRUE, Z = NULL, Simulations = 100, 
  ShowProgressBar = TRUE, CheckArguments = TRUE)
is.DivEst(x)
## S3 method for class 'DivEst'
plot(x, ..., main = NULL, Which = "All",
  Quantiles = c(0.025, 0.975), colValue = "red", lwdValue = 2, ltyValue = 2,
  colQuantiles = "black", lwdQuantiles = 1, ltyQuantiles = 2)
## S3 method for class 'DivEst'
autoplot(object, ..., main = NULL, Which = "All",
  labels = NULL, font.label = list(size=11, face="plain"),
          Quantiles = c(0.025, 0.975), colValue = "red", 
          colQuantiles = "black", ltyQuantiles = 2)
## S3 method for class 'DivEst'
summary(object, ...)

Arguments

Details

Divest estimates the diversity of the metacommunity and partitions it into alpha and beta components.

If Tree is provided, the phylogenetic diversity is calculated else if Z is not NULL, then similarity-based entropy is calculated.

Bootstrap confidence intervals are calculated by drawing simulated communities from a multinomial distribution following the observed frequencies (Marcon et al, 2012; 2014).

Value

A Divest object which is a DivPart object with an additional item in its list:

Divest objects can be summarized and plotted.

Author(s)

Eric Marcon <[email protected]>, Bruno Herault <[email protected]>

References

Marcon, E., Herault, B., Baraloto, C. and Lang, G. (2012). The Decomposition of Shannon's Entropy and a Confidence Interval for Beta Diversity. Oikos 121(4): 516-522.

Marcon, E., Scotti, I., Herault, B., Rossi, V. and Lang, G. (2014). Generalization of the partitioning of Shannon diversity. PLOS One 9(3): e90289.

Marcon, E., Herault, B. (2015). Decomposing Phylodiversity. Methods in Ecology and Evolution 6(3): 333-339.

See Also

DivPart

Examples

# Load Paracou data (number of trees per species in two 1-ha plot of a tropical forest)
data(Paracou618)
# Estimate Shannon diversity.
Estimation <- DivEst(q = 1, Paracou618.MC, Biased = FALSE, Correction = "UnveilJ", 
Simulations = 20)
plot(Estimation)
summary(Estimation)

Description

Partitions the diversity of a metacommunity into alpha and beta components.

Usage

DivPart(q = 1, MC, Biased = TRUE, Correction = "Best", Tree = NULL,
  Normalize = TRUE, Z = NULL, CheckArguments = TRUE)
is.DivPart(x)
## S3 method for class 'DivPart'
plot(x, ...)
## S3 method for class 'DivPart'
autoplot(object, col = ggplot2::GeomRect$default_aes$fill, 
  border = ggplot2::GeomRect$default_aes$colour, ...)
## S3 method for class 'DivPart'
summary(object, ...)

Arguments

Details

DivPart partitions the diversity of the metacommunity into alpha and beta components. It supports estimation-bias correction.

If Tree is provided, the phylogenetic diversity is calculated else if Z is not NULL, then similarity-based entropy is calculated.

Beta diversity/entropy is calculated from Gamma and Alpha when bias correction is required, so community values are not available.

Value

A DivPart object. It is a list:

DivPart objects can be summarized and plotted.

Author(s)

Eric Marcon <[email protected]>, Bruno Herault <[email protected]>

References

Marcon, E., Herault, B., Baraloto, C. and Lang, G. (2012). The Decomposition of Shannon's Entropy and a Confidence Interval for Beta Diversity. Oikos 121(4): 516-522.

Marcon, E., Scotti, I., Herault, B., Rossi, V. and Lang, G. (2014). Generalization of the partitioning of Shannon diversity. PLOS One 9(3): e90289.

Marcon, E., Herault, B. (2015). Decomposing Phylodiversity. Methods in Ecology and Evolution 6(3): 333-339.

Marcon, E., Zhang, Z. and Herault, B. (2014). The decomposition of similarity-based diversity and its bias correction. HAL hal-00989454(version 3).

See Also

DivProfile

Examples

# Load Paracou data (number of trees per species in two 1-ha plot of a tropical forest)
data(Paracou618)
# Estimate Shannon diversity.
summary(DivPart(q = 1, Paracou618.MC, Biased = FALSE) -> dp)
plot(dp)

Description

Calculate the diversity profiles (alpha, beta, gamma) of a metacommunity.

Usage

DivProfile(q.seq = seq(0, 2, 0.1), MC, Biased = TRUE, Correction = "Best", 
  Tree = NULL, Normalize = TRUE, Z = NULL, 
  NumberOfSimulations = 0, Alpha = 0.05, 
  ShowProgressBar = TRUE, CheckArguments = TRUE)
is.DivProfile(x)
## S3 method for class 'DivProfile'
plot(x, ..., main = NULL, xlab = "Order of Diversity",
  ylab = NULL, Which = "All", 
  LineWidth = 2, ShadeColor = "grey75", BorderColor = "red")
## S3 method for class 'DivProfile'
autoplot(object, ..., main = NULL, xlab = "Order of Diversity",
  ylab = NULL, Which = "All", ShadeColor = "grey75", alpha = 0.3, BorderColor = "red", 
  labels = NULL, font.label = list(size=11, face="plain"),
  col = ggplot2::GeomLine$default_aes$colour,
  lty = ggplot2::GeomLine$default_aes$linetype,
  lwd = ggplot2::GeomLine$default_aes$size)
## S3 method for class 'DivProfile'
summary(object, ...)

Arguments

Details

If Tree is provided, the phylogenetic diversity is calculated.

DivPart partitions the diversity of the metacommunity into alpha and beta components. It supports estimation-bias correction.

If Tree is provided, the phylogenetic diversity is calculated else if Z is not NULL, then similarity-based entropy is calculated.

Beta diversity/entropy is calculated from Gamma and Alpha when bias correction is required, so community values are not available.

If NumberOfSimulations is greater than 0, a bootstrap confidence interval is produced by simulating communities from a multinomial distribution following the observed frequencies (Marcon et al, 2012; 2014) and calculating their profiles.

Value

A DivProfile object. It is a list:

DivProfile objects can be summarized and plotted.

Author(s)

Eric Marcon <[email protected]>, Bruno Herault <[email protected]>

References

Marcon, E., Herault, B., Baraloto, C. and Lang, G. (2012). The Decomposition of Shannon's Entropy and a Confidence Interval for Beta Diversity. Oikos 121(4): 516-522.

Marcon, E., Scotti, I., Herault, B., Rossi, V. and Lang, G. (2014). Generalization of the partitioning of Shannon diversity. PLOS One 9(3): e90289.

Marcon, E., Herault, B. (2015). Decomposing Phylodiversity. Methods in Ecology and Evolution 6(3): 333-339.

See Also

DivPart

Examples

# Load Paracou data (number of trees per species in two 1-ha plot of a tropical forest)
data(Paracou618)
# Estimate diversity.
Profile <- DivProfile(q.seq = seq(0, 2, 0.1), Paracou618.MC, Biased = FALSE)
plot(Profile)
autoplot(Profile)
summary(Profile)

Description

Calculates the diversity of order $q$ of a probability vector according to a similarity matrix.

Usage

Dqz(NorP, q = 1, Z = diag(length(NorP)), ...)
bcDqz(Ns, q = 1, Z = diag(length(Ns)), Correction = "Best", CheckArguments = TRUE)
## S3 method for class 'ProbaVector'
Dqz(NorP, q = 1, Z = diag(length(NorP)), ..., 
  CheckArguments = TRUE, Ps = NULL)
## S3 method for class 'AbdVector'
Dqz(NorP, q = 1, Z = diag(length(NorP)), Correction = "Best", ..., 
  CheckArguments = TRUE, Ns = NULL)
## S3 method for class 'integer'
Dqz(NorP, q = 1, Z = diag(length(NorP)), Correction = "Best", ..., 
  CheckArguments = TRUE, Ns = NULL)
## S3 method for class 'numeric'
Dqz(NorP, q = 1, Z = diag(length(NorP)), Correction = "Best", ..., 
  CheckArguments = TRUE, Ps = NULL, Ns = NULL)

Arguments

Details

Diversity is calculated following Leinster and Cobbold (2012): it is the reciprocal of the (generalized) average (of order q) of the community species ordinariness.

A similarity matrix is used (as for Dqz), not a distance matrix as in Ricotta and Szeidl (2006). See the example.

Bias correction requires the number of individuals. Use bcHqz and choose the Correction. Correction techniques are from Marcon et al. (2014).

Currently, the "Best" correction is the max value of "HorvitzThomson" and "MarconZhang".

The functions are designed to be used as simply as possible. Dqz is a generic method. If its first argument is an abundance vector, an integer vector or a numeric vector which does not sum to 1, the bias corrected function bcDqz is called. Explicit calls to bcDqz (with bias correction) or to Dqz.ProbaVector (without correction) are possible to avoid ambiguity. The .integer and .numeric methods accept Ps or Ns arguments instead of NorP for backward compatibility.

Value

A named number equal to the calculated diversity. The name is that of the bias correction used.

References

Leinster, T. and Cobbold, C. (2012). Measuring diversity: the importance of species similarity. Ecology 93(3): 477-489.

Marcon, E., Zhang, Z. and Herault, B. (2014). The decomposition of similarity-based diversity and its bias correction. HAL hal-00989454(version 3).

See Also

Hqz, PhyloDiversity

Examples

# Load Paracou data (number of trees per species in two 1-ha plot of a tropical forest)
data(Paracou618)
# Prepare the similarity matrix
DistanceMatrix <- as.matrix(Paracou618.dist)
# Similarity can be 1 minus normalized distances between species
Z <- 1 - DistanceMatrix/max(DistanceMatrix)
# Calculate diversity of order 2
Dqz(Paracou618.MC$Ns, 2, Z)

Description

This dataset is a light-weight example.

Usage

data(Paracou618)

Format

A named vector.

Examples

data(Paracou618)
EightSpAbundance

Description

This dataset is a leight-weight example.

Usage

data(Paracou618)

Format

An object of class phylog containing a functional tree.

Examples

data(Paracou618)
# Preprocess the tree to be able to plot it 
# without loading ade4 package
plot(Preprocess.Tree(EightSpTree), hang=-0.01)

Description

Expected value of $n^q$ when $n$ follows a Poisson law.

Usage

Enq(n, q)

Arguments

Details

The expectation of $n^q$ when $n$ follows a Poisson ditribution has been derived by Grassberger (1988).

Value

A vector of the same length as n containing the transformed values.

Note

The function is computed using the beta.function.

Its value is 0 for $n-q+1<0$.

References

Grassberger, P. (1988). Finite sample corrections to entropy and dimension estimates. Physics Letters A 128(6-7): 369-373.

Examples

# Compare
n <- c(2,3)
Enq(n, q=2)
# with
n^2

# Result is 1
Enq(n, q=0)
# Result is 0
Enq(n, q=5)

Description

Resamples a community by Monte-Carlo simulations of a multinomial distribution and returns a vector of entropy values to calculate confidence intervals.

Usage

EntropyCI(FUN, Simulations = 100, Ns, BootstrapMethod = "Chao2015", 
    ShowProgressBar = TRUE, ..., CheckArguments = TRUE)

Arguments

Details

This function is used to obtain the distribution of entropy and eventually calculate confidence intervals. It draws simulated communities according to a multinomial distribution with the same number of individuals and probabilities as the actual community. It calculates the entropy of each simulated community. Last, it recenters the distribution of entropy values arounf the actual value of entropy according to Marcon et al. (2012): the estimation bias of simulated communities entropy can not be corrected analytically, but it does not affect the distribution shape.

Diversity can not be recentered this way so diversity function should not be used. Unexpected results will be obtained if inappropriate functions are used.

Value

A numeric vector containing the entropy value of each simulated community.

References

Marcon, E., Herault, B., Baraloto, C. and Lang, G. (2012). The Decomposition of Shannon's Entropy and a Confidence Interval for Beta Diversity. Oikos 121(4): 516-522.

Examples

# Load Paracou data (number of trees per species in two 1-ha plot of a tropical forest)
data(Paracou618)
# Abundance (all estimators will include bias corrrection)
Ns <- as.AbdVector(Paracou618.MC$Ns)
q <- 1
# Estimate entropy and transform it into diversity
RealEst <- expq(Tsallis(Ns, q), q)
# Transform the distribution of Tsallis entropy into diversity
SimulatedDiversity <- expq(EntropyCI(Tsallis, Simulations=50, Ns, q=q), q)
# Figure
plot(density(SimulatedDiversity), col="black", lwd=2, main="", xlab ="Diversity")
abline(v=RealEst, col="red", lwd=2, lty=2)
abline(v=quantile(SimulatedDiversity, probs = 0.025), col="black", lwd=1, lty=3)
abline(v=quantile(SimulatedDiversity, probs = 0.975), col="black", lwd=1, lty=3)
legend("topright", c("Real value", "Confidence interval"), lty=c(2,3),
col=c("red", "black"), inset=0.01)
# Print results
cat("Estimated Diversity:", RealEst)
quantile(SimulatedDiversity, probs = c(0.025, 0.975))

Description

Calculates the deformed exponential of order $q$.

Usage

expq(x, q)
expq.CommunityProfile(Profile)

Arguments

Details

The deformed exponential is defined as $(x(1-q)+1)^{\frac{1}{(1-q)}}$.

For $q>1$, $\ln_q{(+\infty)}=\frac{1}{(q-1)}$ so $\exp_q{(x)}$ is not defined for $x>\frac{1}{(q-1)}$.

expq.CommunityProfile calculates the deformed exponential of a CommunityProfile. Its $x item (the order of diversity) is kept unchanged whilst other items are set to their exponential of order $x. Thus, an entropy profile is transformed into a diversity profile.

Value

A vector of the same length as x containing the transformed values or a CommunityProfile.

References

Marcon, E., Scotti, I., Herault, B., Rossi, V. and Lang, G. (2014). Generalization of the partitioning of Shannon diversity. PLOS One 9(3): e90289.

Tsallis, C. (1994). What are the numbers that experiments provide? Quimica Nova 17(6): 468-471.

See Also

expq

Examples

curve(exp(x), -5, 0, lty=3)  
curve(expq(x, 2), -5, 0, lty=2, add=TRUE)
curve(expq(x, 3), -5, 0, lty=1, add=TRUE)
legend("topleft", legend = c("exp(x)", "exp2(x)", "exp3(x)"), lty = c(1, 2, 3), inset=0.02)

Description

Calculates the reduced-bias diversity of order $q$ of a metacommunity.

Usage

GammaDiversity(MC, q = 1, Correction = "Best", Tree = NULL, Normalize = TRUE, 
  Z = NULL, CheckArguments = TRUE)

Arguments

Details

Entropy is calculated by GammaEntropy and transformed into diversity.

Value

The metacommunity's gamma entropy.

References

Marcon, E., Scotti, I., Herault, B., Rossi, V. and Lang, G. (2014). Generalization of the partitioning of Shannon diversity. PLOS One 9(3): e90289.

Marcon, E., Herault, B. (2015). Decomposing Phylodiversity. Methods in Ecology and Evolution 6(3): 333-339.

Marcon, E., Zhang, Z. and Herault, B. (2014). The decomposition of similarity-based diversity and its bias correction. HAL hal-00989454(version 3).

See Also

GammaEntropy

Examples

# Load Paracou data (number of trees per species in two 1-ha plot of a tropical forest)
data(Paracou618)
# Calculate Simpson gamma diversity
GammaDiversity(Paracou618.MC, 2)
# Compare without correction
GammaDiversity(Paracou618.MC, 2, Correction = "None")
# Estimate phylogenetic Simpson gamma diversity
GammaDiversity(Paracou618.MC, 2, Tree = Paracou618.Taxonomy)

Description

Calculates the reduced-bias Tsallis entropy of order $q$ of a metacommunity.

Usage

GammaEntropy(MC, q = 1, Correction = "Best", Tree = NULL, Normalize = TRUE, 
  Z = NULL, PhyloDetails = FALSE, CheckArguments = TRUE)

Arguments

Details

If Tree is not NULL, then phylogenetic entropy is calculated by bcPhyloEntropy.

Else, if Z is not NULL, then similarity-based entropy is calculated by bcHqz.

Else, neutral entropy is calculated by bcTsallis.

Value

A number equal to the calculated entropy.

References

Marcon, E., Scotti, I., Herault, B., Rossi, V. and Lang, G. (2014). Generalization of the partitioning of Shannon diversity. PLOS One 9(3): e90289.

Marcon, E., Herault, B. (2015). Decomposing Phylodiversity. Methods in Ecology and Evolution 6(3): 333-339.

Marcon, E., Zhang, Z. and Herault, B. (2014). The decomposition of similarity-based diversity and its bias correction. HAL hal-00989454(version 3).

See Also

bcTsallis, bcPhyloEntropy

Examples

# Load Paracou data (number of trees per species in two 1-ha plot of a tropical forest)
data(Paracou618)
# Calculate Simpson gamma entropy
GammaEntropy(Paracou618.MC, 2)
# Compare without correction
GammaEntropy(Paracou618.MC, 2, Correction = "None")
# Estimate phylogenetic Simpson gamma entropy
GammaEntropy(Paracou618.MC, 2, Tree = Paracou618.Taxonomy)

Description

Calculates the Generalized Simpson's entropy of order $r$ of a probability or abundance vector, and its effective number of species.

Usage

GenSimpson(NorP, r = 1, ...)
bcGenSimpson(Ns, r = 1, CheckArguments = TRUE)
## S3 method for class 'ProbaVector'
GenSimpson(NorP, r = 1, ..., 
  CheckArguments = TRUE, Ps = NULL)
## S3 method for class 'AbdVector'
GenSimpson(NorP, r = 1, ..., 
  CheckArguments = TRUE, Ns = NULL)
## S3 method for class 'integer'
GenSimpson(NorP, r = 1, ..., 
  CheckArguments = TRUE, Ns = NULL)
## S3 method for class 'numeric'
GenSimpson(NorP, r = 1, ..., 
  CheckArguments = TRUE, Ps = NULL, Ns = NULL) 
GenSimpsonD(NorP, r = 1, ...)
bcGenSimpsonD(Ns, r = 1, CheckArguments = TRUE)
## S3 method for class 'ProbaVector'
GenSimpsonD(NorP, r = 1, ...,
  CheckArguments = TRUE, Ps = NULL)
## S3 method for class 'AbdVector'
GenSimpsonD(NorP, r = 1, ..., 
  CheckArguments = TRUE, Ns = NULL)
## S3 method for class 'integer'
GenSimpsonD(NorP, r = 1, ..., 
  CheckArguments = TRUE, Ns = NULL)
## S3 method for class 'numeric'
GenSimpsonD(NorP, r = 1, ..., 
  CheckArguments = TRUE, Ps = NULL, Ns = NULL)

Arguments

Details

The Generalized Simpson's Entropy (Zhang and Zhou, 2010) of order $r$ is, in the species accumulation curve, the probability for the individual sampled in rank $r+1$ to belong to a new species. It is a measure of diversity so long as $r$ is lower than the number of species (Grabchak et al., 2016).

Bias correction requires the number of individuals. Use bcGenSimpson. It is limited to orders $r$ less than or equal to the number of individuals in the community.

The effective number of species GenSimpsonD (explicit diversity) has been derived by Grabchak et al. (2016).

The functions are designed to be used as simply as possible. GenSimpson is a generic method. If its first argument is an abundance vector, an integer vector or a numeric vector which does not sum to 1, the bias corrected function bcGenSimpson is called. Explicit calls to bcGenSimpson (with bias correction) or to GenSimpson.ProbaVector (without correction) are possible to avoid ambiguity. The .integer and .numeric methods accept Ps or Ns arguments instead of NorP for backward compatibility.

Value

A named number equal to the calculated index or diversity. The name is either "Biased" or "Unbiased", depending on the estimator used.

Note

The unbiased estimator is calculated by the GenSimp.z function of the EntropyEstimation package.

References

Grabchak, M., Marcon, E., Lang, G., and Zhang, Z. (2017). The Generalized Simpson's Entropy is a Measure of Biodiversity. Plos One, 12(3): e0173305.

Zhang Z. and Zhou J. (2010). Re-parameterization of multinomial distributions and diversity indices. Journal of Statistical Planning and Inference 140(7): 1731-1738.

Examples

# Load Paracou data (number of trees per species in two 1-ha plot of a tropical forest)
data(Paracou618)
# Ns is the total number of trees per species
Ns <- as.AbdVector(Paracou618.MC$Ns)
# Species probabilities
Ps <- as.ProbaVector(Paracou618.MC$Ns)
# Whittaker plot
plot(Ns)

# Calculate GenSimpson entropy of order 1, equal to Simpson's index of diversity
GenSimpson(Ps, 1) 
# Calculate an unbiased estimator of GenSimpson diversity of order 100
GenSimpsonD(Ns, 100)

Description

Calculates the entropy of order $q$ of a probability vector according to a similarity matrix.

Usage

Hqz(NorP, q = 1, Z = diag(length(NorP)),  ...)
bcHqz(Ns, q = 1, Z = diag(length(Ns)), Correction = "Best", SampleCoverage = NULL, 
  CheckArguments = TRUE)
## S3 method for class 'ProbaVector'
Hqz(NorP, q = 1, Z = diag(length(NorP)), 
  ..., CheckArguments = TRUE, Ps = NULL)
## S3 method for class 'AbdVector'
Hqz(NorP, q = 1, Z = diag(length(NorP)), Correction = "Best",
  ..., CheckArguments = TRUE, Ns = NULL)
## S3 method for class 'integer'
Hqz(NorP, q = 1, Z = diag(length(NorP)), Correction = "Best", 
  ..., CheckArguments = TRUE, Ns = NULL)
## S3 method for class 'numeric'
Hqz(NorP, q = 1, Z = diag(length(NorP)), Correction = "Best", 
  ..., CheckArguments = TRUE, Ps = NULL, Ns = NULL)

Arguments

Details

Entropy is calculated following Leinster and Cobbold (2012) after Ricotta and Szeidl (2006): it is the entropy of order q of the community, using species ordinariness as the information function.

A similarity matrix is used (as for Dqz), not a distance matrix as in Ricotta and Szeidl (2006). See the example.

Bias correction requires the number of individuals. Use bcHqz and choose the Correction. Correction techniques are from Marcon et al. (2014).

Currently, the "Best" correction is the max value of "ChaoShen" and "MarconZhang".

The functions are designed to be used as simply as possible. Hqz is a generic method. If its first argument is an abundance vector, an integer vector or a numeric vector which does not sum to 1, the bias corrected function bcHqz is called. Explicit calls to bcHqz (with bias correction) or to Hqz.ProbaVector (without correction) are possible to avoid ambiguity. The .integer and .numeric methods accept Ps or Ns arguments instead of NorP for backward compatibility.

The size of a metacommunity (see MetaCommunity) is unknown so it has to be set according to a rule which does not ensure that its abundances are integer values. Then, classical bias-correction methods do not apply. Providing the SampleCoverage argument allows applying the "ChaoShen" correction to estimate quite well the entropy. DivPart and GammaEntropy functions use this tweak.

Value

A named number equal to the calculated entropy. The name is that of the bias correction used.

References

Leinster, T. and Cobbold, C. (2012). Measuring diversity: the importance of species similarity. Ecology 93(3): 477-489.

Marcon, E., Zhang, Z. and Herault, B. (2014). The decomposition of similarity-based diversity and its bias correction. HAL hal-00989454(version 3).

Ricotta, C. and Szeidl, L. (2006). Towards a unifying approach to diversity measures: Bridging the gap between the Shannon entropy and Rao's quadratic index. Theoretical Population Biology 70(3): 237-243.

See Also

Dqz, PhyloEntropy

Examples

# Load Paracou data (number of trees per species in two 1-ha plot of a tropical forest)
data(Paracou618)
# Prepare the similarity matrix
DistanceMatrix <- as.matrix(EightSpTree$Wdist^2/2)
# Similarity can be 1 minus normalized distances between species
Z <- 1 - DistanceMatrix/max(DistanceMatrix)
# Calculate diversity of order 2
Ps <- EightSpAbundance/sum(EightSpAbundance)
Hqz(Ps, 2, Z)
# Equal to normalized Rao quadratic entropy when q=2
Rao(Ps, EightSpTree)/max(DistanceMatrix)
# But different from PhyloEntropy for all other q, e.g. 1
Hqz(Ps, 1, Z)
summary(PhyloEntropy(Ps, 1, EightSpTree))

Description

Calculates the similarity-based beta entropy of order $q$ of a community belonging to a metacommunity.

Usage

HqzBeta(NorP, NorPexp = NULL, q = 1, Z = diag(length(NorP)), ...)
bcHqzBeta(Ns, Nexp = NULL, q = 1, Z = diag(length(Ns)), Correction = "Best",
          CheckArguments = TRUE)
## S3 method for class 'ProbaVector'
HqzBeta(NorP, NorPexp = NULL, q = 1, Z = diag(length(NorP)),
  ..., CheckArguments = TRUE, Ps = NULL, Pexp = NULL)
## S3 method for class 'AbdVector'
HqzBeta(NorP, NorPexp = NULL, q = 1, Z = diag(length(NorP)), Correction = "Best", 
  ..., CheckArguments = TRUE, Ns = NULL, Nexp = NULL)
## S3 method for class 'integer'
HqzBeta(NorP, NorPexp = NULL, q = 1, Z = diag(length(NorP)), Correction = "Best", 
  ..., CheckArguments = TRUE, Ns = NULL, Nexp = NULL)
## S3 method for class 'numeric'
HqzBeta(NorP, NorPexp = NULL, q = 1, Z = diag(length(NorP)), Correction = "Best", 
  ..., CheckArguments = TRUE, Ps = NULL, Ns = NULL, Pexp = NULL, Nexp = NULL)

Arguments

Details

The derivation of similarity-based beta entropy can be found in Marcon et al. (2014).

Bias correction requires the number of individuals.

Note that beta entropy value is related to alpha entropy (if $q$ is not 1) and cannot be compared accross communities (Jost, 2007). Beta entropy of a community is not meaningful in general, do rather calculate the BetaDiversity of the metacommunity.

The functions are designed to be used as simply as possible. HqzBeta is a generic method. If its first argument is an abundance vector, an integer vector or a numeric vector which does not sum to 1, the bias corrected function bcHqzBeta is called. Explicit calls to bcHqzBeta (with bias correction) or to HqzBeta.ProbaVector (without correction) are possible to avoid ambiguity. The .integer and .numeric methods accept Ps or Ns arguments instead of NorP for backward compatibility.

Value

A named number equal to the calculated entropy. The name is that of the bias correction used.

References

Jost (2007), Partitioning diversity into independent alpha and beta components. Ecology 88(10): 2427-2439.

Marcon, E., Zhang, Z. and Herault, B. (2014). The decomposition of similarity-based diversity and its bias correction. HAL hal-00989454(version 3).

Examples

# Load Paracou data (number of trees per species in two 1-ha plot of a tropical forest)
data(Paracou618)
# Ps is the vector of probabilities
Ps <- as.ProbaVector(Paracou618.MC$Ps)
# Probability distribution of the first plot
Ps1 <- as.ProbaVector(Paracou618.MC$Psi[, 1])
# Prepare the similarity matrix
DistanceMatrix <- as.matrix(Paracou618.dist)
# Similarity can be 1 minus normalized distances between species
Z <- 1 - DistanceMatrix/max(DistanceMatrix)
# Divergence of order 2 between plot 1 and the whole forest
HqzBeta(Ps1, Ps, q=2, Z)

Description

Calculates the Hurlbert entropy of order $k$ of a probability or abundance vector, and its effective number of species.

Usage

Hurlbert(NorP, k = 2, ...)
bcHurlbert(Ns, k = 2, CheckArguments = TRUE)
## S3 method for class 'ProbaVector'
Hurlbert(NorP, k = 2, ..., 
  CheckArguments = TRUE, Ps = NULL)
## S3 method for class 'AbdVector'
Hurlbert(NorP, k = 2, ..., 
  CheckArguments = TRUE, Ns = NULL)
## S3 method for class 'integer'
Hurlbert(NorP, k = 2, ...,
  CheckArguments = TRUE, Ns = NULL)
## S3 method for class 'numeric'
Hurlbert(NorP, k = 2, ...,
  CheckArguments = TRUE, Ps = NULL, Ns = NULL) 
HurlbertD(NorP, k = 2, ...)
bcHurlbertD(Ns, k = 2, CheckArguments = TRUE)
## S3 method for class 'ProbaVector'
HurlbertD(NorP, k = 2, ...,
  CheckArguments = TRUE, Ps = NULL)
## S3 method for class 'AbdVector'
HurlbertD(NorP, k = 2, ...,
  CheckArguments = TRUE, Ns = NULL)
## S3 method for class 'integer'
HurlbertD(NorP, k = 2, ...,
  CheckArguments = TRUE, Ns = NULL)
## S3 method for class 'numeric'
HurlbertD(NorP, k = 2, ...,
  CheckArguments = TRUE, Ps = NULL, Ns = NULL)

Arguments

Details

Hurlbert's index of diversity (1971) of order $k$ is the expected number of species in a sample of size $k$.

Bias correction requires the number of individuals. Use bcHurlbert. It is limited to orders $k$ less than or equal to the number of individuals in the community.

The effective number of species HurlbertD (explicit diversity) has been derived by Dauby & Hardy (2012). It is calculated numerically. bcHurlbertD calculates it from the bias-corrected index bcHurlbert.

The functions are designed to be used as simply as possible. Hurlbert is a generic method. If its first argument is an abundance vector, an integer vector or a numeric vector which does not sum to 1, the bias corrected function bcHurlbert is called. Explicit calls to bcHurlbert (with bias correction) or to Hurlbert.ProbaVector (without correction) are possible to avoid ambiguity. The .integer and .numeric methods accept Ps or Ns arguments instead of NorP for backward compatibility.

Value

A named number equal to the calculated index or diversity. The name is either "Biased" or "Unbiased", depending on the estimator used.

References

Dauby G. & Hardy O.J. (2012) Sampled-based estimation of diversity sensu stricto by transforming Hurlbert diversities into effective number of species. Ecography 35(7): 661-672.

Hurlbert (1971) The Nonconcept of Species Diversity: A Critique and Alternative Parameters. Ecology 52(4): 577-586.

Examples

# Load Paracou data (number of trees per species in two 1-ha plot of a tropical forest)
data(Paracou618)
# Ns is the total number of trees per species
Ns <- as.AbdVector(Paracou618.MC$Ns)
# Species probabilities
Ps <- as.ProbaVector(Paracou618.MC$Ns)
# Whittaker plot
plot(Ns)

# Calculate Hurlbert entropy of order 2, equal to Simpson's index of diversity
Hurlbert(Ps, 2) 
# Calculate an unbiased estimator of Hurlbert entropy of order 2
Hurlbert(Ns, 2)

Description

Calculates the generalized Kullback-Leibler divergence between an observed and an expected probability distribution.

Usage

KLq(Ps, Pexp, q = 1, CheckArguments = TRUE)

Arguments

Details

The generalized Kullback-Leibler divergence (Borland et al., 1998) converges to the Kullback-Leibler divergence (Kullback and Leibler, 1951) when $q$ tends to 1. It is used to calculate the generalized beta entropy (Marcon et al., 2014).

Value

A number equal to the generalized Kullback-Leibler divergence between the probability distributions.

References

Borland, L., Plastino, A. R. and Tsallis, C. (1998). Information gain within nonextensive thermostatistics. Journal of Mathematical Physics 39(12): 6490-6501.

Kullback, S. and Leibler, R. A. (1951). On Information and Sufficiency. The Annals of Mathematical Statistics 22(1): 79-86.

Marcon, E., Scotti, I., Herault, B., Rossi, V. and Lang, G. (2014). Generalization of the partitioning of Shannon diversity. PLOS One 9(3): e90289.

See Also

TsallisBeta

Examples

# Load Paracou data (number of trees per species in two 1-ha plot of a tropical forest)
data(Paracou618)
# Ps is the vector of probabilities
Ps <- Paracou618.MC$Ps
# Probability distribution of the first plot
Ps1 <- Paracou618.MC$Psi[, 1]
# Divergence of order 2 between the first plot and the whole forest
KLq(Ps1, Ps, 2)

Description

Calculates the deformed logarithm of order $q$.

Usage

lnq(x, q)
lnq.CommunityProfile(Profile)

Arguments

Details

The deformed logarithm is defined as $\ln_q{x}=\frac{(x^{(1-q)}-1)}{(1-q)}$.

The shape of the deformed logarithm is similar to that of the regular one. $\ln_1{x}=\log{x}$.

For $q>1$, $\ln_q{(+\infty)}=\frac{1}{(q-1)}$.

lnq.CommunityProfile calculates the deformed logarithm of a CommunityProfile. Its $x item (the order of diversity) is kept unchanged whilst other items are set to their logarithm of order $x. Thus, a diversity profile is transformed into an entropy profile.

Value

A vector of the same length as x containing the transformed values or a CommunityProfile.

References

Tsallis, C. (1994). What are the numbers that experiments provide? Quimica Nova 17(6): 468-471.

See Also

expq

Examples

curve(log(x), 0, 1, lty=1)
curve(lnq(x, 2), 0, 1, lty=2, add=TRUE)
curve(lnq(x, 3), 0, 1, lty=3, add=TRUE)  
legend("topleft", legend = c("log(x)", "ln2(x)", "ln3(x)"), lty = c(1, 2, 3), inset=0.02)

Description

Tools to manipulate meta-communities. From a list of meta-communities, MergeMC creates a metacommunity whose communities are each original metacommunity. MergeC creates a metacommunity whose communities are each original community. ShuffleMC randomly assigns original communities to a metacommunity, keeping original weights, and returns a list of meta-communities.

Usage

MergeMC(MClist, Weights = rep(1, length(MClist)), CheckArguments = TRUE)
MergeC(MClist, Weights = rep(1, length(MClist)), CheckArguments = TRUE)
ShuffleMC(MClist, Weights = rep(1, length(MClist)), CheckArguments = TRUE)

Arguments

Details

MergeMC is used for hierarchical partitioning of diversity. The gamma diversity of communities of the list becomes alpha diversity of the merged meta-community.

MergeC creates a new meta-community by mixing original ones. Original communities are kept, their new weight is the product of their original weight and the weight of their original meta-community.

ShuffleMC is used for simulations of the null hypothesis that all metacommunities of the list are identical.

Value

MergeMC and MergeC return a MetaCommunity.

ShuffleMC returns a list of MetaCommunity objects.

See Also

MetaCommunity

Examples

# First meta-community
(df <- data.frame(C1 = c(10, 10, 10, 10), C2 = c(0, 20, 35, 5),
  C3 = c(25, 15, 0, 2), row.names = c("sp1", "sp2", "sp3", "sp4")))
w <- c(1, 2, 1)
MC1 <- MetaCommunity(Abundances = df, Weights = w)
# Second meta-community
(df <- data.frame(C1 = c(10, 4), C2 = c(3, 4), row.names = c("sp1", "sp5")))
w <- c(3, 2)
MC2 <- MetaCommunity(Abundances = df, Weights = w)

# Merge communities
plot(MergeC(list(MC1, MC2)), main="Merged communities")
# Merge metacommunities
plot(MergeMC(list(MC1, MC2)), main="Merged meta-communities")
smc <- ShuffleMC(list(MC1, MC2))
plot(MergeMC(smc), main="Shuffled, then Merged meta-communities")

Description

Methods for objects of type "MCdiversity".

Usage

is.MCdiversity(x)
## S3 method for class 'MCdiversity'
plot(x, ...)
## S3 method for class 'MCdiversity'
autoplot(object, col = ggplot2::GeomCol$default_aes$fill,
          border = ggplot2::GeomCol$default_aes$colour, ...)
## S3 method for class 'MCdiversity'
summary(object, ...)

Arguments

Value

Meta-community diversity objects are lists containing:

is.MCdiversity returns TRUE if the object is of class MCdiversity.

summary.MCdiversity returns a summary of the object's value.

Description

Methods for objects of type "MCentropy".

Usage

is.MCentropy(x)
## S3 method for class 'MCentropy'
plot(x, ...)
## S3 method for class 'MCentropy'
autoplot(object, col = ggplot2::GeomCol$default_aes$fill,
          border = ggplot2::GeomCol$default_aes$colour, ...)
## S3 method for class 'MCentropy'
summary(object, ...)

Arguments

Value

Meta-community entropy objects are lists containing:

is.MCentropy returns TRUE if the object is of class MCentropy.

summary.MCentropy returns a summary of the object's value.

Description

Methods for objects of type "MetaCommunity".

Usage

MetaCommunity(Abundances, Weights = rep(1, ncol(Abundances)))
is.MetaCommunity(x)
## S3 method for class 'MetaCommunity'
summary(object, ...)
## S3 method for class 'MetaCommunity'
plot(x, ...)

Arguments

Details

In the entropart package, individuals of different "species" are counted in several "communities" which are agregated to define a "metacommunity".

This is a naming convention, which may correspond to plots in a forest inventory or any data organized the same way.

Alpha and beta entropies of communities are summed according to Weights and the probability to find a species in the metacommunity is the weighted average of probabilities in communities.

The simplest way to import data is to organize it into two text files. The first file should contain abundance data: the first column named Species for species names, and a column for each community.

The second file should contain the community weights in two columns. The first one, named Communities should contain their names and the second one, named Weights, their weights.

Files can be read and data imported by code such as:

Abundances <- read.csv(file="Abundances.csv", row.names = 1)
Weights <- read.csv(file="Weights.csv")
MC <- MetaCommunity(Abundances, Weights)

Value

An object of class MetaCommunity is a list:

is.MetaCommunity returns TRUE if the object is of class MetaCommunity.

summary.MetaCommunity returns a summary of the object's value.

plot.MetaCommunity plots it.

Examples

# Use BCI data from vegan package
if (require(vegan, quietly = TRUE)) {
  # Load BCI data (number of trees per species in each 1-ha plot of a tropical forest)
  data(BCI)
  # BCI dataframe must be transposed (its lines are plots, not species)
  BCI.df <- as.data.frame(t(BCI))
  # Create a metacommunity object from a matrix of abundances and a vector of weights
  # (here, all plots have a weight equal to 1)
  MC <- MetaCommunity(BCI.df)
}

Description

Calculates the scale parameter $u$ that maximizes the variance of the similarity matrix $exp(-u*DistanceMatrix)$.

Usage

Optimal.Similarity(Distance, CheckArguments = TRUE)

Arguments

Details

The similarity matrix used by Dqz) can be optimized following Marcon et al. (2014) such that the variance of similarities between pairs of species is maximized. See the example.

Value

A list:

References

Marcon, E., Zhang, Z. and Herault, B. (2014). The decomposition of similarity-based diversity and its bias correction. HAL hal-00989454(version 3).

See Also

Dqz

Examples

# Load Paracou data (number of trees per species in two 1-ha plot of a tropical forest)
data(Paracou618)
# Prepare the similarity matrix. The square root of Paracou618.dist is euclidean.
optimal <- Optimal.Similarity(sqrt(Paracou618.dist))
# Optimal scale
optimal$u
# Calculate diversity of order 2
bcDqz(Paracou618.MC$Ns, 2, optimal$Matrix)

Description

This dataset is from Paracou field station, French Guiana, managed by Cirad. Traits are detailed in Marcon and Herault (2014), the distance matrix was built following Paine et al. (2011).

Usage

data(Paracou618)

Format

An object of class dist.

Source

Permanent data census of Paracou.

References

Gourlet-Fleury, S., Guehl, J. M. and Laroussinie, O., Eds. (2004). Ecology & management of a neotropical rainforest. Lessons drawn from Paracou, a long-term experimental research site in French Guiana. Paris, Elsevier.

Marcon, E., Herault, B. (2015). Decomposing Phylodiversity. Methods in Ecology and Evolution 6(3): 333-339.

Paine, C. E. T., Baraloto, C., Chave, J., and Herault, B. (2011). Functional traits of individual trees reveal ecological constraints on community assembly in tropical rain forests. Oikos, 120(5), 720-727.

Examples

data(Paracou618)
plot(density(Paracou618.dist, from=0), main="Distances between species")

Description

This dataset is from Paracou field station, French Guiana, managed by Cirad. Traits are detailed in Marcon and Herault (2014), the tree was built following Paine et al. (2011), based on Paracou618.dist.

Usage

data(Paracou618)

Format

An object of class hclust.

Source

Permanent data census of Paracou.

References

Gourlet-Fleury, S., Guehl, J. M. and Laroussinie, O., Eds. (2004). Ecology & management of a neotropical rainforest. Lessons drawn from Paracou, a long-term experimental research site in French Guiana. Paris, Elsevier.

Marcon, E., Herault, B. (2015). Decomposing Phylodiversity. Methods in Ecology and Evolution 6(3): 333-339.

Paine, C. E. T., Baraloto, C., Chave, J., and Herault, B. (2011). Functional traits of individual trees reveal ecological constraints on community assembly in tropical rain forests. Oikos, 120(5), 720-727.

Examples

data(Paracou618)
plot(Paracou618.Functional)

Description

This dataset is from Paracou field station, French Guiana, managed by Cirad.

Usage

data(Paracou618)

Format

An object of class MetaCommunity made of two communities and 425 species.

Source

Permanent data census of Paracou and Marcon et al. (2012).

References

Gourlet-Fleury, S., Guehl, J. M. and Laroussinie, O., Eds. (2004). Ecology & management of a neotropical rainforest. Lessons drawn from Paracou, a long-term experimental research site in French Guiana. Paris, Elsevier.

Marcon, E., F. Puech, et al. (2012). Characterizing the relative spatial structure of point patterns. International Journal of Ecology 2012(Article ID 619281): 11.

Examples

data(Paracou618)
summary(Paracou618.MC)

Description

This dataset is from Paracou field station, French Guiana, managed by Cirad.

Usage

data(Paracou618)

Format

An object of class "phylo" (see read.tree) containing a taxonomy.

Source

Permanent data census of Paracou.

References

Gourlet-Fleury, S., Guehl, J. M. and Laroussinie, O., Eds. (2004). Ecology & management of a neotropical rainforest. Lessons drawn from Paracou, a long-term experimental research site in French Guiana. Paris, Elsevier.

Examples

data(Paracou618)
plot(Paracou618.Taxonomy, type="fan", show.tip.label=FALSE)

Description

Calculates Faith's PD / Petchey and Gaston' FD of a community described by a probability vector and a phylogenetic / functional tree.

Usage

PDFD(Ps, Tree, CheckArguments = TRUE)

Arguments

Details

PD and FD are defined as the total legth of the branches of the tree.

The probability vector is used to select branches: branches with probability 0 are eliminated.

Bias correction requires the number of individuals to estimate sample Coverage.

Use bcPhyloDiversity(Ps, 0, Tree) and choose the Correction.

Value

A named number equal to the calculated diversity. The name is that of the bias correction used.

References

Faith, D. P. (1992). Conservation evaluation and phylogenetic diversity. Biological Conservation 61(1): 1-10.

Petchey, O. L. and Gaston, K. J. (2002). Functional diversity (FD), species richness and community composition. Ecology Letters 5: 402-411.

See Also

bcPhyloDiversity

Examples

# Load Paracou data (number of trees per species in two 1-ha plot of a tropical forest
#      and their taxonomy)
data(Paracou618)
# Ps is the vector of probabilities
Ps <- Paracou618.MC$Ps
# Calculate the phylogenetic Shannon diversity of the plot
PDFD(Ps, Paracou618.Taxonomy)

Description

Cuts the tree into slices separated by nodes, applies the function to each slice and returns the weighted (by slice lengths) sum of the results.

Usage

PhyloApply(Tree, FUN, NorP, Normalize = TRUE, dfArgs = NULL,
           ..., CheckArguments = TRUE)

Arguments

Details

This funtion is generally not used directly. It is a tool to calculate PhyloEntropy and PhyloDiversity.

Intervals (slices) separate two cuts (nodes) in a tree: no node is found at heights contained in an interval.

Objects of class PPtree are returned by Preprocess.Tree.

... allow passing arguments to the function but they can't change along the tree. If necessary, dfArgs allow passing a different value for each slice of the tree.

Value

An object of class PhyloValue. It is a list:

References

Marcon, E., Herault, B. (2015). Decomposing Phylodiversity. Methods in Ecology and Evolution 6(3): 333-339.

See Also

Preprocess.Tree

Examples

# Load Paracou data (number of trees per species in two 1-ha plot of a tropical forest
#      and their taxonomy)
data(Paracou618)
# Plot the taxonomy
plot(Paracou618.Taxonomy, type="fan", show.tip.label=FALSE)
# Calculate the mean number of trees (individuals) per species 
# (Cuts are 1=species, 2=genus, 3=family)
summary(PhyloApply(Paracou618.Taxonomy, mean, Paracou618.MC$Ns, TRUE))

Description

Calculates the phylogenetic beta entropy of order $q$ of a a community belonging to a metacommunity.

Usage

PhyloBetaEntropy(NorP, NorPexp = NULL, q = 1, Tree, Normalize = TRUE, ...)
bcPhyloBetaEntropy(Ns, Nexp, q = 1, Tree, Normalize = TRUE, 
  Correction = "Best", CheckArguments = TRUE)
## S3 method for class 'ProbaVector'
PhyloBetaEntropy(NorP, NorPexp = NULL, q = 1, Tree, Normalize = TRUE, 
  ..., CheckArguments = TRUE, Ps = NULL, Pexp = NULL)
## S3 method for class 'AbdVector'
PhyloBetaEntropy(NorP, NorPexp = NULL, q = 1, Tree, Normalize = TRUE, 
  Correction = "Best", ..., CheckArguments = TRUE, Ns = NULL, Nexp = NULL)
## S3 method for class 'integer'
PhyloBetaEntropy(NorP, NorPexp = NULL, q = 1, Tree, Normalize = TRUE, 
  Correction = "Best", ..., CheckArguments = TRUE, Ns = NULL, Nexp = NULL)
## S3 method for class 'numeric'
PhyloBetaEntropy(NorP, NorPexp = NULL, q = 1, Tree, Normalize = TRUE, 
  Correction = "Best", ..., CheckArguments = TRUE, Ps = NULL, Ns = NULL, 
  Pexp = NULL, Nexp = NULL)

Arguments

Details

The phylogenetic entropy is the generalization of HCDT entropy to unequal species distances (Pavoine et al., 2009).

Calculation relies on TsallisBeta and PhyloApply.

Bias correction requires the number of individuals to estimate sample Coverage. Use bcPhyloBetaEntropy and choose the Correction.

Note that beta entropy value is related to alpha entropy (if $q$ is not 1) and cannot be compared accross communities (Jost, 2007). Beta entropy of a community is not meaningful in general, do rather calculate the PhyloDiversity of the metacommunity.