Package 'divent'

Description

Measures of Diversity and Entropy

Details

This package is a reboot of the entropart package (Marcon and Hérault 2015).

Author(s)

Maintainer: Eric Marcon [email protected] (ORCID)

References

Marcon E, Hérault B (2015). “Entropart, an R Package to Measure and Partition Diversity.” Journal of Statistical Software, 67(8), 1–26. doi:10.18637/jss.v067.i08.

See Also

Useful links:

• https://ericmarcon.github.io/divent/

• https://github.com/EricMarcon/divent

• Report bugs at https://github.com/EricMarcon/divent/issues

Description

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

Usage

abd_freq_count(
  abd,
  level = NULL,
  probability_estimator = c("naive", "Chao2013", "Chao2015", "ChaoShen"),
  unveiling = c("none", "uniform", "geometric"),
  richness_estimator = c("jackknife", "iChao1", "Chao1", "rarefy", "naive"),
  coverage_estimator = c("ZhangHuang", "Chao", "Turing", "Good"),
  check_arguments = TRUE
)

Arguments

Details

The Abundance Frequency Count (Chao and Jost 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 probabilities and eq. (5) of (Chao et al. 2014).

Value

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

References

Chao A, Gotelli NJ, Hsieh TC, Sander EL, Ma KH, Colwell RK, Ellison AM (2014). “Rarefaction and Extrapolation with Hill Numbers: A Framework for Sampling and Estimation in Species Diversity Studies.” Ecological Monographs, 84(1), 45–67. doi:10.1890/13-0133.1.

Chao A, Jost L (2015). “Estimating Diversity and Entropy Profiles via Discovery Rates of New Species.” Methods in Ecology and Evolution, 6(8), 873–882. doi:10.1111/2041-210X.12349.

Examples

abd_freq_count(as.numeric(paracou_6_abd[1, ]))

Description

Utilities for community abundances (objects of class "abundances").

Usage

abd_species(abundances, check_arguments = TRUE)

abd_sum(abundances, as_numeric = FALSE, check_arguments = TRUE)

prob_species(species_distribution, check_arguments = TRUE)

Arguments

Value

abd_species() returns a tibble containing the species abundance columns only, to simplify numeric operations.

prob_species() returns the same tibble but values are probabilities.

abd_sum() returns the sample sizes of the communities in a numeric vector.

Examples

abd_species(paracou_6_abd)
abd_sum(paracou_6_abd)

Description

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

Usage

accum_ent_phylo(x, ...)

## S3 method for class 'numeric'
accum_ent_phylo(
  x,
  tree,
  q = 0,
  normalize = TRUE,
  levels = NULL,
  probability_estimator = c("Chao2015", "Chao2013", "ChaoShen", "naive"),
  unveiling = c("geometric", "uniform", "none"),
  richness_estimator = c("rarefy", "jackknife", "iChao1", "Chao1", "naive"),
  jack_alpha = 0.05,
  jack_max = 10,
  coverage_estimator = c("ZhangHuang", "Chao", "Turing", "Good"),
  n_simulations = 0,
  alpha = 0.05,
  show_progress = TRUE,
  ...,
  check_arguments = TRUE
)

## S3 method for class 'abundances'
accum_ent_phylo(
  x,
  tree,
  q = 0,
  normalize = TRUE,
  levels = NULL,
  probability_estimator = c("Chao2015", "Chao2013", "ChaoShen", "naive"),
  unveiling = c("geometric", "uniform", "none"),
  richness_estimator = c("rarefy", "jackknife", "iChao1", "Chao1", "naive"),
  jack_alpha = 0.05,
  jack_max = 10,
  coverage_estimator = c("ZhangHuang", "Chao", "Turing", "Good"),
  gamma = FALSE,
  n_simulations = 0,
  alpha = 0.05,
  show_progress = TRUE,
  ...,
  check_arguments = TRUE
)

accum_div_phylo(x, ...)

## S3 method for class 'numeric'
accum_div_phylo(
  x,
  tree,
  q = 0,
  normalize = TRUE,
  levels = NULL,
  probability_estimator = c("Chao2015", "Chao2013", "ChaoShen", "naive"),
  unveiling = c("geometric", "uniform", "none"),
  richness_estimator = c("rarefy", "jackknife", "iChao1", "Chao1", "naive"),
  jack_alpha = 0.05,
  jack_max = 10,
  coverage_estimator = c("ZhangHuang", "Chao", "Turing", "Good"),
  n_simulations = 0,
  alpha = 0.05,
  show_progress = TRUE,
  ...,
  check_arguments = TRUE
)

## S3 method for class 'abundances'
accum_div_phylo(
  x,
  tree,
  q = 0,
  normalize = TRUE,
  levels = NULL,
  probability_estimator = c("Chao2015", "Chao2013", "ChaoShen", "naive"),
  unveiling = c("geometric", "uniform", "none"),
  richness_estimator = c("rarefy", "jackknife", "iChao1", "Chao1", "naive"),
  jack_alpha = 0.05,
  jack_max = 10,
  coverage_estimator = c("ZhangHuang", "Chao", "Turing", "Good"),
  gamma = FALSE,
  n_simulations = 0,
  alpha = 0.05,
  show_progress = TRUE,
  ...,
  check_arguments = TRUE
)

Arguments

Details

accum_ent_phylo() or accum_div_phylo() estimate the phylogenetic diversity or entropy accumulation curve of a distribution. See ent_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.

Interpolation and extrapolation of integer orders of diversity are from Chao et al. (2014). The asymptotic richness is adjusted so that the extrapolated part of the accumulation joins the observed value at the sample size.

"accumulation" objects can be plotted. They generalize the classical Species Accumulation Curves (SAC) which are diversity accumulation of order $q=0$.

Value

A tibble with the site names, the estimators used and the accumulated entropy or diversity at each level of sampling effort.

References

Chao A, Gotelli NJ, Hsieh TC, Sander EL, Ma KH, Colwell RK, Ellison AM (2014). “Rarefaction and Extrapolation with Hill Numbers: A Framework for Sampling and Estimation in Species Diversity Studies.” Ecological Monographs, 84(1), 45–67. doi:10.1890/13-0133.1.

Examples

# Richness accumulation up to the sample size. 
# 100 simulations only to save time.
autoplot(
  accum_div_phylo(mock_3sp_abd, tree = mock_3sp_tree, n_simulations = 100)
)

Description

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

Usage

accum_tsallis(x, ...)

## S3 method for class 'numeric'
accum_tsallis(
  x,
  q = 0,
  levels = seq_len(sum(x)),
  probability_estimator = c("Chao2015", "Chao2013", "ChaoShen", "naive"),
  unveiling = c("geometric", "uniform", "none"),
  richness_estimator = c("rarefy", "jackknife", "iChao1", "Chao1", "naive"),
  jack_alpha = 0.05,
  jack_max = 10,
  coverage_estimator = c("ZhangHuang", "Chao", "Turing", "Good"),
  n_simulations = 0,
  alpha = 0.05,
  show_progress = TRUE,
  ...,
  check_arguments = TRUE
)

## S3 method for class 'abundances'
accum_tsallis(
  x,
  q = 0,
  levels = NULL,
  probability_estimator = c("Chao2015", "Chao2013", "ChaoShen", "naive"),
  unveiling = c("geometric", "uniform", "none"),
  richness_estimator = c("rarefy", "jackknife", "iChao1", "Chao1", "naive"),
  jack_alpha = 0.05,
  jack_max = 10,
  coverage_estimator = c("ZhangHuang", "Chao", "Turing", "Good"),
  n_simulations = 0,
  alpha = 0.05,
  show_progress = TRUE,
  ...,
  check_arguments = TRUE
)

accum_hill(x, ...)

## S3 method for class 'numeric'
accum_hill(
  x,
  q = 0,
  levels = seq_len(sum(x)),
  probability_estimator = c("Chao2015", "Chao2013", "ChaoShen", "naive"),
  unveiling = c("geometric", "uniform", "none"),
  richness_estimator = c("rarefy", "jackknife", "iChao1", "Chao1", "naive"),
  jack_alpha = 0.05,
  jack_max = 10,
  coverage_estimator = c("ZhangHuang", "Chao", "Turing", "Good"),
  n_simulations = 0,
  alpha = 0.05,
  show_progress = TRUE,
  ...,
  check_arguments = TRUE
)

## S3 method for class 'abundances'
accum_hill(
  x,
  q = 0,
  levels = NULL,
  probability_estimator = c("Chao2015", "Chao2013", "ChaoShen", "naive"),
  unveiling = c("geometric", "uniform", "none"),
  richness_estimator = c("rarefy", "jackknife", "iChao1", "Chao1", "naive"),
  jack_alpha = 0.05,
  jack_max = 10,
  coverage_estimator = c("ZhangHuang", "Chao", "Turing", "Good"),
  n_simulations = 0,
  alpha = 0.05,
  show_progress = TRUE,
  ...,
  check_arguments = TRUE
)

Arguments

Details

accum_hill() or accum_tsallis() estimate the diversity or entropy accumulation curve of a distribution. See ent_tsallis for details about the computation of entropy at each level of interpolation and extrapolation.

In accumulation curves, extrapolation is done by estimating the asymptotic distribution of the community and estimating entropy at different levels by interpolation.

Interpolation and extrapolation of integer orders of diversity are from Chao et al. (2014). The asymptotic richness is adjusted so that the extrapolated part of the accumulation joins the observed value at the sample size.

"accumulation" objects can be plotted. They generalize the classical Species Accumulation Curves (SAC) which are diversity accumulation of order $q=0$.

Value

A tibble with the site names, the estimators used and the accumulated entropy or diversity at each level of sampling effort.

References

Chao A, Gotelli NJ, Hsieh TC, Sander EL, Ma KH, Colwell RK, Ellison AM (2014). “Rarefaction and Extrapolation with Hill Numbers: A Framework for Sampling and Estimation in Species Diversity Studies.” Ecological Monographs, 84(1), 45–67. doi:10.1890/13-0133.1.

Examples

# Paracou 6 subplot 1
autoplot(accum_hill(paracou_6_abd[1, ]))

Description

A spatial accumulation is a measure of diversity with respect to the distance from individuals.

Usage

## S3 method for class 'accum_sp'
plot(
  x,
  ...,
  q = dimnames(x$accumulation)$q[1],
  type = "l",
  main = "accumulation of ...",
  xlab = "Sample size...",
  ylab = "Diversity...",
  ylim = NULL,
  show_h0 = TRUE,
  line_width = 2,
  col_shade = "grey75",
  col_border = "red"
)

## S3 method for class 'accum_sp'
autoplot(
  object,
  ...,
  q = dimnames(object$accumulation)$q[1],
  main = "Accumulation of ...",
  xlab = "Sample size...",
  ylab = "Diversity...",
  ylim = NULL,
  show_h0 = TRUE,
  col_shade = "grey75",
  col_border = "red"
)

plot_map(
  accum,
  q = dimnames(accum$accumulation)$q[1],
  neighborhood = dplyr::last(colnames(accum$neighborhoods)),
  sigma = spatstat.explore::bw.scott(accum$X, isotropic = TRUE),
  allow_jitter = TRUE,
  weighted = FALSE,
  adjust = 1,
  dim_x = 128,
  dim_y = 128,
  main = "",
  col = grDevices::terrain.colors(256),
  contour = TRUE,
  contour_levels = 10,
  contour_col = "dark red",
  points = FALSE,
  pch = 20,
  point_col = "black",
  suppress_margins = TRUE,
  ...,
  check_arguments = TRUE
)

Arguments

Details

Objects of class accum_sp contain the value of diversity (accum_sp_diversity objects), entropy (accum_sp_entropy objects) or mixing (accum_sp_mixing objects) at distances from the individuals.

These objects are lists:

• X contains the dbmss::wmppp point pattern,

• accumulation is a 3-dimensional array, with orders of diveristy in rows, neighborhood size (number of points or distance) in columns and a single slice for the observed entropy, diversity or mixing.

• neighborhoods is a similar 3-dimensional array with one slice per point of X.

They can be plotted or mapped.

Value

plot.accum_sp() returns NULL.

autoplot.accum_sp() returns a ggplot2::ggplot object.

plot_map returns a spatstat.geom::im object that can be used to produce alternative maps.

Examples

# Generate a random community
X <- rspcommunity(1, size = 50, species_number = 10)
# Calculate the species accumulation curve
accum <- accum_sp_hill(X, orders = 0, r = c(0, 0.2), individual = TRUE)
# Plot the local richness at distance = 0.2
plot_map(accum, q = 0, neighborhood = 0.2)

Description

Spatial Diversity and Entropy Accumulation Curves represent the accumulation of entropy and diversity with respect to the distance from individuals

Usage

accum_sp_tsallis(
  X,
  orders = 0,
  neighbors = 1:ceiling(X$n/2),
  r = NULL,
  correction = c("none", "extrapolation"),
  richness_estimator = c("rarefy", "jackknife", "iChao1", "Chao1", "naive"),
  individual = FALSE,
  show_progress = TRUE,
  check_arguments = TRUE
)

accum_sp_hill(
  X,
  orders = 0,
  neighbors = 1:ceiling(X$n/2),
  r = NULL,
  correction = c("none", "extrapolation"),
  richness_estimator = c("rarefy", "jackknife", "iChao1", "Chao1", "naive"),
  h0 = c("none", "multinomial", "random location", "binomial"),
  alpha = 0.05,
  n_simulations = 100,
  individual = FALSE,
  show_progress = TRUE,
  check_arguments = TRUE
)

accum_mixing(
  X,
  orders = 0,
  neighbors = 1:ceiling(X$n/2),
  r = NULL,
  correction = c("none", "extrapolation"),
  richness_estimator = c("rarefy", "jackknife", "iChao1", "Chao1", "naive"),
  h0 = c("none", "multinomial", "random location", "binomial"),
  alpha = 0.05,
  n_simulations = 100,
  individual = FALSE,
  show_progress = TRUE,
  check_arguments = TRUE
)

Arguments

Details

accum_sp_hill() or accum_sp_tsallis() estimate the diversity or entropy accumulation curve of a distribution.

Value

An accum_sp object, that is also either an accum_sp_diversity, accum_sp_entropy or accum_sp_mixing object.

Examples

# Generate a random community
X <- rspcommunity(1, size = 50, species_number = 3)
# Calculate the accumulation of richness 
accum <- accum_sp_hill(X)
plot(accum, q = 0)
# along distance
accum_r <- accum_sp_hill(X, orders = 1, r = seq(0, .5, .05))
autoplot(accum_r, q = 1)

Description

Calculate a window containing all points of a point pattern. The window is not convex but as close as possible to the points.

Usage

alphahull(X, alpha = NULL)

Arguments

Details

The typical use of this function is to define a narrow window around a point pattern that has been created with a default, rectangle window.

The window is built by the alphahull::ashape() function and then transformed into a spatstat.geom::owin.object. The alpha parameter determines the smallest size of zones excluded from the window. If it is not specified, a first attempt is 1/256 of the diameter of the existing window of X. If the shape cannot be calculated, alpha is doubled and a new attempt is made.

Value

A window, i.e. a spatstat.geom::owin.object.

See Also

spatstat.geom::convexhull

Examples

# Simulate a point pattern
if (require(spatstat.random)) {
  X <- rpoispp(50)
  plot(X)
  # Calculate its border
  X$window <- alphahull(X)
  plot(X)
}

Description

Plot objects of class "accumulation" produced by accum_hill and other accumulation functions.

Usage

## S3 method for class 'accumulation'
autoplot(
  object,
  ...,
  main = NULL,
  xlab = "Sample Size",
  ylab = NULL,
  shade_color = "grey75",
  alpha = 0.3,
  lty = ggplot2::GeomLine$default_aes$linetype,
  lwd = ggplot2::GeomLine$default_aes$linewidth
)

Arguments

Value

A ggplot2::ggplot object.

Examples

# Species accumulation curve
autoplot(accum_hill(mock_3sp_abd))

Description

Plot objects of class "profile" produced by profile_hill and other profile functions.

Usage

## S3 method for class 'profile'
autoplot(
  object,
  ...,
  main = NULL,
  xlab = "Order of Diversity",
  ylab = "Diversity",
  shade_color = "grey75",
  alpha = 0.3,
  lty = ggplot2::GeomLine$default_aes$linetype,
  lwd = ggplot2::GeomLine$default_aes$linewidth
)

Arguments

Value

A ggplot2::ggplot object.

Examples

# Diversity profile curve
autoplot(profile_hill(mock_3sp_abd))

Description

This method is from the dbmss package. See dbmss::autoplot.wmppp.

Usage

## S3 method for class 'wmppp'
autoplot(
  object,
  ...,
  show.window = TRUE,
  MaxPointTypes = 6,
  Other = "Other",
  main = NULL,
  xlab = NULL,
  ylab = NULL,
  LegendLabels = NULL,
  labelSize = "Weight",
  labelColor = "Type",
  palette = "Set1",
  windowColor = "black",
  windowFill = "transparent",
  alpha = 1
)

Arguments

Value

A ggplot2::ggplot.

Examples

autoplot(paracou_6_wmppp)

Description

coverage() calculates an estimator of the sample coverage of a community described by its abundance vector. coverage_to_size() estimates the sample size corresponding to the chosen sample coverage.

Usage

coverage(x, ...)

## S3 method for class 'numeric'
coverage(
  x,
  estimator = c("ZhangHuang", "Chao", "Turing", "Good"),
  level = NULL,
  as_numeric = FALSE,
  ...,
  check_arguments = TRUE
)

## S3 method for class 'abundances'
coverage(
  x,
  estimator = c("ZhangHuang", "Chao", "Turing", "Good"),
  level = NULL,
  ...,
  check_arguments = TRUE
)

coverage_to_size(x, ...)

## S3 method for class 'numeric'
coverage_to_size(
  x,
  sample_coverage,
  estimator = c("ZhangHuang", "Chao", "Turing", "Good"),
  as_numeric = FALSE,
  ...,
  check_arguments = TRUE
)

## S3 method for class 'abundances'
coverage_to_size(
  x,
  sample_coverage,
  estimator = c("ZhangHuang", "Chao", "Turing", "Good"),
  ...,
  check_arguments = TRUE
)

Arguments

Details

The sample coverage $C$ of a community is the total probability of occurrence 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 et al. (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.

coverage_to_size() returns a number equal to the sample size corresponding to the chosen sample coverage.

References

Chao A, Gotelli NJ, Hsieh TC, Sander EL, Ma KH, Colwell RK, Ellison AM (2014). “Rarefaction and Extrapolation with Hill Numbers: A Framework for Sampling and Estimation in Species Diversity Studies.” Ecological Monographs, 84(1), 45–67. doi:10.1890/13-0133.1.

Chao A, Lee S, Chen T (1988). “A Generalized Good's Nonparametric Coverage Estimator.” Chinese Journal of Mathematics, 16, 189–199. 43836340.

Chao A, Shen T (2010). Program SPADE: Species Prediction and Diversity Estimation. Program and User's Guide.. CARE.

Good IJ (1953). “The Population Frequency of Species and the Estimation of Population Parameters.” Biometrika, 40(3/4), 237–264. doi:10.1093/biomet/40.3-4.237.

Zhang Z, Huang H (2007). “Turing's Formula Revisited.” Journal of Quantitative Linguistics, 14(2-3), 222–241. doi:10.1080/09296170701514189.

Examples

coverage(paracou_6_abd)
coverage_to_size(paracou_6_abd, sample_coverage = 0.9)

Description

Estimate the diversity sensu stricto, i.e. the Hill (1973) number of species from abundance or probability data.

Usage

div_hill(x, q = 1, ...)

## S3 method for class 'numeric'
div_hill(
  x,
  q = 1,
  estimator = c("UnveilJ", "ChaoJost", "ChaoShen", "GenCov", "Grassberger", "Marcon",
    "UnveilC", "UnveiliC", "ZhangGrabchak", "naive", "Bonachela", "Holste"),
  level = NULL,
  probability_estimator = c("Chao2015", "Chao2013", "ChaoShen", "naive"),
  unveiling = c("geometric", "uniform", "none"),
  richness_estimator = c("jackknife", "iChao1", "Chao1", "naive"),
  jack_alpha = 0.05,
  jack_max = 10,
  coverage_estimator = c("ZhangHuang", "Chao", "Turing", "Good"),
  sample_coverage = NULL,
  as_numeric = FALSE,
  ...,
  check_arguments = TRUE
)

## S3 method for class 'species_distribution'
div_hill(
  x,
  q = 1,
  estimator = c("UnveilJ", "ChaoJost", "ChaoShen", "GenCov", "Grassberger", "Marcon",
    "UnveilC", "UnveiliC", "ZhangGrabchak", "naive", "Bonachela", "Holste"),
  level = NULL,
  probability_estimator = c("Chao2015", "Chao2013", "ChaoShen", "naive"),
  unveiling = c("geometric", "uniform", "none"),
  richness_estimator = c("jackknife", "iChao1", "Chao1", "naive"),
  jack_alpha = 0.05,
  jack_max = 10,
  coverage_estimator = c("ZhangHuang", "Chao", "Turing", "Good"),
  gamma = FALSE,
  as_numeric = FALSE,
  ...,
  check_arguments = TRUE
)

Arguments

Details

Several estimators are available to deal with incomplete sampling.

Bias correction requires the number of individuals.

Estimation techniques are from Chao and Shen (2003), Grassberger (1988),Holste et al. (1998), Bonachela et al. (2008), Marcon et al. (2014) which is actually the max value of "ChaoShen" and "Grassberger", Zhang and Grabchak (2014), Chao et al. (2015), Chao and Jost (2015) and Marcon (2015).

The ChaoJost estimator Chao et al. (2013); Chao and Jost (2015) contains an unbiased part concerning observed species, equal to that of Zhang and Grabchak (2014), and a (biased) estimator of the remaining bias based on the estimation of the species-accumulation curve. It is very efficient but slow if the number of individuals is more than a few hundreds.

The unveiled estimators rely on Chao et al. (2015), completed by Marcon (2015). The actual probabilities of observed species are estimated and completed by a geometric distribution of the probabilities of unobserved species. The number of unobserved species is estimated by the Chao1 estimator (UnveilC), following Chao et al. (2015), or by the iChao1 (UnveiliC) or the jackknife (UnveilJ). The UnveilJ estimator often has a lower bias but a greater variance (Marcon 2015). It is a good first choice thanks to the versatility of the jackknife estimator of richness.

Estimators by Bonachela et al. (2008) and Holste et al. (1998) are rarely used.

To estimate $\gamma$ diversity, 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 sample_coverage argument allows applying the ChaoShen and Grassberger estimators to estimate quite well the entropy.

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 accum_hill for details.

Value

A tibble with the site names, the estimators used and the estimated diversity.

References

Bonachela JA, Hinrichsen H, Muñoz MA (2008). “Entropy Estimates of Small Data Sets.” Journal of Physics A: Mathematical and Theoretical, 41(202001), 1–9. doi:10.1088/1751-8113/41/20/202001.

Chao A, Gotelli NJ, Hsieh TC, Sander EL, Ma KH, Colwell RK, Ellison AM (2014). “Rarefaction and Extrapolation with Hill Numbers: A Framework for Sampling and Estimation in Species Diversity Studies.” Ecological Monographs, 84(1), 45–67. doi:10.1890/13-0133.1.

Chao A, Hsieh TC, Chazdon RL, Colwell RK, Gotelli NJ (2015). “Unveiling the Species-Rank Abundance Distribution by Generalizing Good-Turing Sample Coverage Theory.” Ecology, 96(5), 1189–1201. doi:10.1890/14-0550.1.

Chao A, Jost L (2015). “Estimating Diversity and Entropy Profiles via Discovery Rates of New Species.” Methods in Ecology and Evolution, 6(8), 873–882. doi:10.1111/2041-210X.12349.

Chao A, Shen T (2003). “Nonparametric Estimation of Shannon's Index of Diversity When There Are Unseen Species in Sample.” Environmental and Ecological Statistics, 10(4), 429–443. doi:10.1023/A:1026096204727.

Chao A, Wang Y, Jost L (2013). “Entropy and the Species Accumulation Curve: A Novel Entropy Estimator via Discovery Rates of New Species.” Methods in Ecology and Evolution, 4(11), 1091–1100. doi:10.1111/2041-210x.12108.

Grassberger P (1988). “Finite Sample Corrections to Entropy and Dimension Estimates.” Physics Letters A, 128(6-7), 369–373. doi:10.1016/0375-9601(88)90193-4.

Hill MO (1973). “Diversity and Evenness: A Unifying Notation and Its Consequences.” Ecology, 54(2), 427–432. doi:10.2307/1934352.

Holste D, Große I, Herzel H (1998). “Bayes' Estimators of Generalized Entropies.” Journal of Physics A: Mathematical and General, 31(11), 2551–2566.

Marcon E (2015). “Practical Estimation of Diversity from Abundance Data.” HAL, 01212435(version 2).

Marcon E, Scotti I, Hérault B, Rossi V, Lang G (2014). “Generalization of the Partitioning of Shannon Diversity.” Plos One, 9(3), e90289. doi:10.1371/journal.pone.0090289.

Zhang Z, Grabchak M (2014). “Nonparametric Estimation of Kullback-Leibler Divergence.” Neural computation, 26(11), 2570–2593. doi:10.1162/NECO_a_00646, 25058703.

Examples

# Diversity of each community
div_hill(paracou_6_abd, q = 2)
# gamma diversity
div_hill(paracou_6_abd, q = 2, gamma = TRUE)

# At 80% coverage
div_hill(paracou_6_abd, q = 2, level = 0.8)

Description

Estimate the diversity sensu stricto, i.e. the effective number of species number of species Dauby and Hardy (2012) from abundance or probability data.

Usage

div_hurlbert(x, k = 1, ...)

## S3 method for class 'numeric'
div_hurlbert(
  x,
  k = 2,
  estimator = c("Hurlbert", "naive"),
  as_numeric = FALSE,
  ...,
  check_arguments = TRUE
)

## S3 method for class 'species_distribution'
div_hurlbert(
  x,
  k = 2,
  estimator = c("Hurlbert", "naive"),
  as_numeric = FALSE,
  ...,
  check_arguments = TRUE
)

Arguments

Details

Several estimators are available to deal with incomplete sampling.

Bias correction requires the number of individuals.

Estimation techniques are from Hurlbert (1971).

Hurlbert's diversity cannot be estimated at a specified level of interpolation or extrapolation, and diversity partioning is not available.

Value

A tibble with the site names, the estimators used and the estimated diversity.

References

Dauby G, Hardy OJ (2012). “Sampled-Based Estimation of Diversity Sensu Stricto by Transforming Hurlbert Diversities into Effective Number of Species.” Ecography, 35(7), 661–672. doi:10.1111/j.1600-0587.2011.06860.x.

Hurlbert SH (1971). “The Nonconcept of Species Diversity: A Critique and Alternative Parameters.” Ecology, 52(4), 577–586. doi:10.2307/1934145.

Examples

# Diversity of each community
div_hurlbert(paracou_6_abd, k = 2)

Description

Calculate $\gamma$, $\beta$ and $\alpha$ diversities of a metacommunity.

Usage

div_part(
  abundances,
  q = 1,
  estimator = c("UnveilJ", "ChaoJost", "ChaoShen", "GenCov", "Grassberger", "Holste",
    "Marcon", "UnveilC", "UnveiliC", "ZhangGrabchak"),
  level = NULL,
  probability_estimator = c("Chao2015", "Chao2013", "ChaoShen", "naive"),
  unveiling = c("geometric", "uniform", "none"),
  richness_estimator = c("jackknife", "iChao1", "Chao1", "naive"),
  jack_alpha = 0.05,
  jack_max = 10,
  coverage_estimator = c("ZhangHuang", "Chao", "Turing", "Good"),
  check_arguments = TRUE
)

Arguments

Details

The function computes $\gamma$ diversity after building a metacommunity from local communities according to their weight (Marcon et al. 2014). $\alpha$ entropy is the weighted mean local entropy, converted into Hill numbers to obtain $\alpha$ diversity. $\beta$ diversity is obtained as the ratio of $\gamma$ to $\alpha$.

Value

A tibble with diversity values at each scale.

References

Marcon E, Scotti I, Hérault B, Rossi V, Lang G (2014). “Generalization of the Partitioning of Shannon Diversity.” Plos One, 9(3), e90289. doi:10.1371/journal.pone.0090289.

Examples

div_part(paracou_6_abd)

Description

Estimate the diversity of species from abundance or probability data and a phylogenetic tree. Several estimators are available to deal with incomplete sampling.

Usage

div_phylo(x, tree, q = 1, ...)

## S3 method for class 'numeric'
div_phylo(
  x,
  tree,
  q = 1,
  normalize = TRUE,
  estimator = c("UnveilJ", "ChaoJost", "ChaoShen", "GenCov", "Grassberger", "Marcon",
    "UnveilC", "UnveiliC", "ZhangGrabchak", "naive", "Bonachela", "Holste"),
  level = NULL,
  probability_estimator = c("Chao2015", "Chao2013", "ChaoShen", "naive"),
  unveiling = c("geometric", "uniform", "none"),
  richness_estimator = c("jackknife", "iChao1", "Chao1", "naive"),
  jack_alpha = 0.05,
  jack_max = 10,
  coverage_estimator = c("ZhangHuang", "Chao", "Turing", "Good"),
  as_numeric = FALSE,
  ...,
  check_arguments = TRUE
)

## S3 method for class 'species_distribution'
div_phylo(
  x,
  tree,
  q = 1,
  normalize = TRUE,
  estimator = c("UnveilJ", "ChaoJost", "ChaoShen", "GenCov", "Grassberger", "Marcon",
    "UnveilC", "UnveiliC", "ZhangGrabchak", "naive", "Bonachela", "Holste"),
  level = NULL,
  probability_estimator = c("Chao2015", "Chao2013", "ChaoShen", "naive"),
  unveiling = c("geometric", "uniform", "none"),
  richness_estimator = c("jackknife", "iChao1", "Chao1", "naive"),
  jack_alpha = 0.05,
  jack_max = 10,
  coverage_estimator = c("ZhangHuang", "Chao", "Turing", "Good"),
  gamma = FALSE,
  ...,
  check_arguments = TRUE
)

Arguments

Details

Bias correction requires the number of individuals. See div_hill for estimators.

Entropy 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 accum_tsallis for details.

Value

A tibble with the site names, the estimators used and the estimated diversity

References

Chao A, Gotelli NJ, Hsieh TC, Sander EL, Ma KH, Colwell RK, Ellison AM (2014). “Rarefaction and Extrapolation with Hill Numbers: A Framework for Sampling and Estimation in Species Diversity Studies.” Ecological Monographs, 84(1), 45–67. doi:10.1890/13-0133.1.

Examples

div_phylo(paracou_6_abd, tree = paracou_6_taxo, q = 2)

# At 80% coverage
div_phylo(paracou_6_abd, tree = paracou_6_taxo, q = 2, level = 0.8)

# Gamma entropy
div_phylo(paracou_6_abd, tree = paracou_6_taxo, q = 2, gamma = TRUE)

Description

Estimate the number of species from abundance or probability data. Several estimators are available to deal with incomplete sampling.

Usage

div_richness(x, ...)

## S3 method for class 'numeric'
div_richness(
  x,
  estimator = c("jackknife", "iChao1", "Chao1", "rarefy", "naive"),
  jack_alpha = 0.05,
  jack_max = 10,
  level = NULL,
  probability_estimator = c("Chao2015", "Chao2013", "ChaoShen", "naive"),
  unveiling = c("geometric", "uniform", "none"),
  coverage_estimator = c("ZhangHuang", "Chao", "Turing", "Good"),
  as_numeric = FALSE,
  ...,
  check_arguments = TRUE
)

## S3 method for class 'species_distribution'
div_richness(
  x,
  estimator = c("jackknife", "iChao1", "Chao1", "rarefy", "naive"),
  jack_alpha = 0.05,
  jack_max = 10,
  level = NULL,
  probability_estimator = c("Chao2015", "Chao2013", "ChaoShen", "naive"),
  unveiling = c("geometric", "uniform", "none"),
  coverage_estimator = c("ZhangHuang", "Chao", "Turing", "Good"),
  gamma = FALSE,
  as_numeric = FALSE,
  ...,
  check_arguments = TRUE
)

Arguments

Details

Bias correction requires the number of individuals. Chao's estimation techniques are from Chao et al. (2014) and Chiu et al. (2014). The Jackknife estimator is calculated by a straight adaptation of the code by Ji-Ping Wang (jackknife in package SPECIES). The optimal order is selected according to Burnham and Overton (1978); Burnham and Overton (1979). Many other estimators are available elsewhere, the ones implemented here are necessary for other entropy estimations.

Richness can be estimated at a specified level of interpolation or extrapolation, either a chosen sample size or sample coverage (Chiu et al. 2014), rather than its asymptotic value. Extrapolation relies on the estimation of the asymptotic richness. If probability_estimator is "naive", then the asymptotic estimation of richness is made using the chosen estimator, else the asymptotic distribution of the community is derived and its estimated richness adjusted so that the richness of a sample of this distribution of the size of the actual sample has the richness of the actual sample.

Value

A tibble with the site names, the estimators used and the estimated numbers of species.

References

Burnham KP, Overton WS (1978). “Estimation of the Size of a Closed Population When Capture Probabilities Vary among Animals.” Biometrika, 65(3), 625–633. doi:10.2307/2335915.

Burnham KP, Overton WS (1979). “Robust Estimation of Population Size When Capture Probabilities Vary among Animals.” Ecology, 60(5), 927–936. doi:10.2307/1936861.

Chao A, Gotelli NJ, Hsieh TC, Sander EL, Ma KH, Colwell RK, Ellison AM (2014). “Rarefaction and Extrapolation with Hill Numbers: A Framework for Sampling and Estimation in Species Diversity Studies.” Ecological Monographs, 84(1), 45–67. doi:10.1890/13-0133.1.

Chiu C, Wang Y, Walther BA, Chao A (2014). “An Improved Nonparametric Lower Bound of Species Richness via a Modified Good-Turing Frequency Formula.” Biometrics, 70(3), 671–682. doi:10.1111/biom.12200, 24945937.

Examples

# Diversity of each community
div_richness(paracou_6_abd)
# gamma diversity
div_richness(paracou_6_abd, gamma = TRUE)

# At 80% coverage
div_richness(paracou_6_abd, level = 0.8)

Description

Estimate the diversity of species from abundance or probability data and a similarity matrix between species. Several estimators are available to deal with incomplete sampling. Bias correction requires the number of individuals.

Usage

div_similarity(x, similarities, q = 1, ...)

## S3 method for class 'numeric'
div_similarity(
  x,
  similarities = diag(length(x)),
  q = 1,
  estimator = c("UnveilJ", "Max", "ChaoShen", "MarconZhang", "UnveilC", "UnveiliC",
    "naive"),
  probability_estimator = c("Chao2015", "Chao2013", "ChaoShen", "naive"),
  unveiling = c("geometric", "uniform", "none"),
  jack_alpha = 0.05,
  jack_max = 10,
  coverage_estimator = c("ZhangHuang", "Chao", "Turing", "Good"),
  sample_coverage = NULL,
  as_numeric = FALSE,
  ...,
  check_arguments = TRUE
)

## S3 method for class 'species_distribution'
div_similarity(
  x,
  similarities = diag(sum(!colnames(x) %in% non_species_columns)),
  q = 1,
  estimator = c("UnveilJ", "Max", "ChaoShen", "MarconZhang", "UnveilC", "UnveiliC",
    "naive"),
  probability_estimator = c("Chao2015", "Chao2013", "ChaoShen", "naive"),
  unveiling = c("geometric", "uniform", "none"),
  jack_alpha = 0.05,
  jack_max = 10,
  coverage_estimator = c("ZhangHuang", "Chao", "Turing", "Good"),
  gamma = FALSE,
  ...,
  check_arguments = TRUE
)

Arguments

Details

All species of the species_distribution must be found in the matrix of similarities if it is named. If it is not, its size must equal the number of species. Then, the order of species is assumed to be the same as that of the species_distribution.

Similarity-Based diversity can't be interpolated of extrapolated as of the state of the art.

Value

A tibble with the site names, the estimators used and the estimated diversity.

Examples

# Similarity matrix
Z <- fun_similarity(paracou_6_fundist)
# Diversity of each community
div_similarity(paracou_6_abd, similarities = Z, q = 2)
# gamma diversity
div_similarity(paracou_6_abd, similarities = Z, q = 2, gamma = TRUE)

Description

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

Usage

e_n_q(n, q)

Arguments

Details

The expectation of $n^q$ when $n$ follows a Poisson distribution was derived by Grassberger (1988).

It is computed using the beta function. Its value is 0 for $n-q+1<0$, and close to 0 when $n=q$, which is not a correct estimate: it should not be used when $q > n$.

Value

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

References

Grassberger P (1988). “Finite Sample Corrections to Entropy and Dimension Estimates.” Physics Letters A, 128(6-7), 369–373. doi:10.1016/0375-9601(88)90193-4.

Examples

n <- 10
q <- 2
# Compare
e_n_q(n, q)
# with (empirical estimation)
mean(rpois(1000, lambda = n)^q)
# and (naive estimation)
n^q

Description

Estimate the Hurlbert entropy (Hurlbert 1971) of species from abundance or probability data. Several estimators are available to deal with incomplete sampling.

Usage

ent_hurlbert(x, k = 2, ...)

## S3 method for class 'numeric'
ent_hurlbert(
  x,
  k = 2,
  estimator = c("Hurlbert", "naive"),
  as_numeric = FALSE,
  ...,
  check_arguments = TRUE
)

## S3 method for class 'species_distribution'
ent_hurlbert(
  x,
  k = 2,
  estimator = c("Hurlbert", "naive"),
  as_numeric = FALSE,
  ...,
  check_arguments = TRUE
)

Arguments

Details

Bias correction requires the number of individuals. See div_hurlbert for estimators.

Hurlbert's entropy cannot be estimated at a specified level of interpolation or extrapolation, and entropy partitioning is not available.

Value

A tibble with the site names, the estimators used and the estimated entropy.

References

Hurlbert SH (1971). “The Nonconcept of Species Diversity: A Critique and Alternative Parameters.” Ecology, 52(4), 577–586. doi:10.2307/1934145.

Examples

# Entropy of each community
ent_hurlbert(paracou_6_abd, k = 2)

Description

Estimate the entropy of species from abundance or probability data and a phylogenetic tree. Several estimators are available to deal with incomplete sampling.

Usage

ent_phylo(x, tree, q = 1, ...)

## S3 method for class 'numeric'
ent_phylo(
  x,
  tree,
  q = 1,
  normalize = TRUE,
  estimator = c("UnveilJ", "ChaoJost", "ChaoShen", "GenCov", "Grassberger", "Marcon",
    "UnveilC", "UnveiliC", "ZhangGrabchak", "naive", "Bonachela", "Holste"),
  level = NULL,
  probability_estimator = c("Chao2015", "Chao2013", "ChaoShen", "naive"),
  unveiling = c("geometric", "uniform", "none"),
  richness_estimator = c("jackknife", "iChao1", "Chao1", "naive"),
  jack_alpha = 0.05,
  jack_max = 10,
  coverage_estimator = c("ZhangHuang", "Chao", "Turing", "Good"),
  as_numeric = FALSE,
  ...,
  check_arguments = TRUE
)

## S3 method for class 'species_distribution'
ent_phylo(
  x,
  tree,
  q = 1,
  normalize = TRUE,
  estimator = c("UnveilJ", "ChaoJost", "ChaoShen", "GenCov", "Grassberger", "Marcon",
    "UnveilC", "UnveiliC", "ZhangGrabchak", "naive", "Bonachela", "Holste"),
  level = NULL,
  probability_estimator = c("Chao2015", "Chao2013", "ChaoShen", "naive"),
  unveiling = c("geometric", "uniform", "none"),
  richness_estimator = c("jackknife", "iChao1", "Chao1", "naive"),
  jack_alpha = 0.05,
  jack_max = 10,
  coverage_estimator = c("ZhangHuang", "Chao", "Turing", "Good"),
  gamma = FALSE,
  ...,
  check_arguments = TRUE
)

Arguments

Details

Bias correction requires the number of individuals. See div_hill for estimators.

Entropy 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 accum_tsallis for details.

Value

A tibble with the site names, the estimators used and the estimated entropy.

References

Chao A, Gotelli NJ, Hsieh TC, Sander EL, Ma KH, Colwell RK, Ellison AM (2014). “Rarefaction and Extrapolation with Hill Numbers: A Framework for Sampling and Estimation in Species Diversity Studies.” Ecological Monographs, 84(1), 45–67. doi:10.1890/13-0133.1.

Examples

# Entropy of each community
ent_phylo(paracou_6_abd, tree = paracou_6_taxo, q = 2)
# Gamma entropy
ent_phylo(paracou_6_abd, tree = paracou_6_taxo, q = 2, gamma = TRUE)

# At 80% coverage
ent_phylo(paracou_6_abd, tree = paracou_6_taxo, q = 2, level = 0.8)

Description

Estimate the quadratic entropy (Rao 1982) of species from abundance or probability data. An estimator (Lande 1996) is available to deal with incomplete sampling.

Usage

ent_rao(x, ...)

## S3 method for class 'numeric'
ent_rao(
  x,
  distances = NULL,
  tree = NULL,
  normalize = TRUE,
  estimator = c("Lande", "naive"),
  as_numeric = FALSE,
  ...,
  check_arguments = TRUE
)

## S3 method for class 'species_distribution'
ent_rao(
  x,
  distances = NULL,
  tree = NULL,
  normalize = TRUE,
  estimator = c("Lande", "naive"),
  gamma = FALSE,
  ...,
  check_arguments = TRUE
)

Arguments

Details

Rao's entropy is phylogenetic or similarity-based entropy of order 2. ent_phylo and ent_similarity with argument q = 2 provide more estimators and allow estimating entropy at a chosen level.

All species of the species_distribution must be found in the matrix of distances if it is named. If it is not or if x is numeric, its size must equal the number of species. Then, the order of species is assumed to be the same as that of the species_distribution or its numeric equivalent.

Value

A tibble with the site names, the estimators used and the estimated entropy.

References

Lande R (1996). “Statistics and Partitioning of Species Diversity, and Similarity among Multiple Communities.” Oikos, 76(1), 5–13. doi:10.2307/3545743.

Rao CR (1982). “Diversity and Dissimilarity Coefficients: A Unified Approach.” Theoretical Population Biology, 21, 24–43. doi:10.1016/0040-5809(82)90004-1.

Examples

# Entropy of each community
ent_rao(paracou_6_abd, tree = paracou_6_taxo)
# Similar to (but estimators are not the same) 
ent_phylo(paracou_6_abd, tree = paracou_6_taxo, q = 2)

# Functional entropy
ent_rao(paracou_6_abd, distances = paracou_6_fundist)

# gamma entropy
ent_rao(paracou_6_abd, tree = paracou_6_taxo, gamma = TRUE)

Description

Estimate the entropy (Shannon 1948) of species from abundance or probability data. Several estimators are available to deal with incomplete sampling.

Usage

ent_shannon(x, ...)

## S3 method for class 'numeric'
ent_shannon(
  x,
  estimator = c("UnveilJ", "ChaoJost", "ChaoShen", "GenCov", "Grassberger", "Marcon",
    "UnveilC", "UnveiliC", "ZhangGrabchak", "naive", "Bonachela", "Grassberger2003",
    "Holste", "Miller", "Schurmann", "ZhangHz"),
  level = NULL,
  probability_estimator = c("Chao2015", "Chao2013", "ChaoShen", "naive"),
  unveiling = c("geometric", "uniform", "none"),
  richness_estimator = c("jackknife", "iChao1", "Chao1", "naive"),
  jack_alpha = 0.05,
  jack_max = 10,
  coverage_estimator = c("ZhangHuang", "Chao", "Turing", "Good"),
  as_numeric = FALSE,
  ...,
  check_arguments = TRUE
)

## S3 method for class 'species_distribution'
ent_shannon(
  x,
  estimator = c("UnveilJ", "ChaoJost", "ChaoShen", "GenCov", "Grassberger", "Marcon",
    "UnveilC", "UnveiliC", "ZhangGrabchak", "naive", "Bonachela", "Grassberger2003",
    "Holste", "Miller", "Schurmann", "ZhangHz"),
  level = NULL,
  probability_estimator = c("Chao2015", "Chao2013", "ChaoShen", "naive"),
  unveiling = c("geometric", "uniform", "none"),
  richness_estimator = c("jackknife", "iChao1", "Chao1", "naive"),
  jack_alpha = 0.05,
  jack_max = 10,
  coverage_estimator = c("ZhangHuang", "Chao", "Turing", "Good"),
  gamma = FALSE,
  as_numeric = FALSE,
  ...,
  check_arguments = TRUE
)

Arguments

Details

Bias correction requires the number of individuals.

See div_hill for non-specific estimators. Shannon-specific estimators are from Miller (1955), Grassberger (2003), Schürmann (2004) and Zhang (2012). More estimators can be found in the entropy package.

Entropy 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 accum_tsallis for details.

Value

A tibble with the site names, the estimators used and the estimated entropy.

References

Chao A, Gotelli NJ, Hsieh TC, Sander EL, Ma KH, Colwell RK, Ellison AM (2014). “Rarefaction and Extrapolation with Hill Numbers: A Framework for Sampling and Estimation in Species Diversity Studies.” Ecological Monographs, 84(1), 45–67. doi:10.1890/13-0133.1.

Grassberger P (2003). “Entropy Estimates from Insufficient Samplings.” arXiv Physics e-prints, 0307138(v2).

Miller GA (1955). “Note on the Bias of Information Estimates.” In Quastler H (ed.), Information Theory in Psychology: Problems and Methods, 95–100. Free Press, Glencoe, Ill.

Schürmann T (2004). “Bias Analysis in Entropy Estimation.” Journal of Physics A: Mathematical and General, 37(27), L295–L301. doi:10.1088/0305-4470/37/27/L02.

Shannon CE (1948). “A Mathematical Theory of Communication.” The Bell System Technical Journal, 27(3), 379–423, 623–656. doi:10.1002/j.1538-7305.1948.tb01338.x.

Zhang Z (2012). “Entropy Estimation in Turing's Perspective.” Neural Computation, 24(5), 1368–1389. doi:10.1162/NECO_a_00266.

Examples

# Entropy of each community
ent_shannon(paracou_6_abd)
# gamma entropy
ent_shannon(paracou_6_abd, gamma = TRUE)

# At 80% coverage
ent_shannon(paracou_6_abd, level = 0.8)

Description

Estimate the entropy of species from abundance or probability data and a similarity matrix between species. Several estimators are available to deal with incomplete sampling. Bias correction requires the number of individuals.

Usage

ent_similarity(x, similarities, q = 1, ...)

## S3 method for class 'numeric'
ent_similarity(
  x,
  similarities = diag(length(x)),
  q = 1,
  estimator = c("UnveilJ", "Max", "ChaoShen", "MarconZhang", "UnveilC", "UnveiliC",
    "naive"),
  probability_estimator = c("Chao2015", "Chao2013", "ChaoShen", "naive"),
  unveiling = c("geometric", "uniform", "none"),
  jack_alpha = 0.05,
  jack_max = 10,
  coverage_estimator = c("ZhangHuang", "Chao", "Turing", "Good"),
  sample_coverage = NULL,
  as_numeric = FALSE,
  ...,
  check_arguments = TRUE
)

## S3 method for class 'species_distribution'
ent_similarity(
  x,
  similarities = diag(sum(!colnames(x) %in% non_species_columns)),
  q = 1,
  estimator = c("UnveilJ", "Max", "ChaoShen", "MarconZhang", "UnveilC", "UnveiliC",
    "naive"),
  probability_estimator = c("Chao2015", "Chao2013", "ChaoShen", "naive"),
  unveiling = c("geometric", "uniform", "none"),
  jack_alpha = 0.05,
  jack_max = 10,
  coverage_estimator = c("ZhangHuang", "Chao", "Turing", "Good"),
  gamma = FALSE,
  ...,
  check_arguments = TRUE
)

Arguments

Details

All species of the species_distribution must be found in the matrix of similarities if it is named. If it is not or if x is numeric, its size must equal the number of species. Then, the order of species is assumed to be the same as that of the species_distribution or its numeric equivalent.

Similarity-Based entropy can't be interpolated of extrapolated as of the state of the art.

Value

A tibble with the site names, the estimators used and the estimated entropy.

Examples

# Similarity matrix
Z <- fun_similarity(paracou_6_fundist)
# Diversity of each community
ent_similarity(paracou_6_abd, similarities = Z, q = 2)
# gamma diversity
ent_similarity(paracou_6_abd, similarities = Z, q = 2, gamma = TRUE)

Description

Estimate the entropy (Simpson 1949) of species from abundance or probability data. Several estimators are available to deal with incomplete sampling.

Usage

ent_simpson(x, ...)

## S3 method for class 'numeric'
ent_simpson(
  x,
  estimator = c("Lande", "UnveilJ", "ChaoJost", "ChaoShen", "GenCov", "Grassberger",
    "Marcon", "UnveilC", "UnveiliC", "ZhangGrabchak", "naive", "Bonachela", "Holste"),
  level = NULL,
  probability_estimator = c("Chao2015", "Chao2013", "ChaoShen", "naive"),
  unveiling = c("geometric", "uniform", "none"),
  richness_estimator = c("jackknife", "iChao1", "Chao1", "naive"),
  jack_alpha = 0.05,
  jack_max = 10,
  coverage_estimator = c("ZhangHuang", "Chao", "Turing", "Good"),
  as_numeric = FALSE,
  ...,
  check_arguments = TRUE
)

## S3 method for class 'species_distribution'
ent_simpson(
  x,
  estimator = c("Lande", "UnveilJ", "ChaoJost", "ChaoShen", "GenCov", "Grassberger",
    "Marcon", "UnveilC", "UnveiliC", "ZhangGrabchak", "naive", "Bonachela", "Holste"),
  level = NULL,
  probability_estimator = c("Chao2015", "Chao2013", "ChaoShen", "naive"),
  unveiling = c("geometric", "uniform", "none"),
  richness_estimator = c("jackknife", "iChao1", "Chao1", "naive"),
  jack_alpha = 0.05,
  jack_max = 10,
  coverage_estimator = c("ZhangHuang", "Chao", "Turing", "Good"),
  gamma = FALSE,
  as_numeric = FALSE,
  ...,
  check_arguments = TRUE
)

Arguments

Details

Bias correction requires the number of individuals. See div_hill for non-specific estimators.

Simpson-specific estimator is from Lande (1996).

Entropy 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 accum_tsallis for details.

Value

A tibble with the site names, the estimators used and the estimated entropy.

References

Chao A, Gotelli NJ, Hsieh TC, Sander EL, Ma KH, Colwell RK, Ellison AM (2014). “Rarefaction and Extrapolation with Hill Numbers: A Framework for Sampling and Estimation in Species Diversity Studies.” Ecological Monographs, 84(1), 45–67. doi:10.1890/13-0133.1.

Lande R (1996). “Statistics and Partitioning of Species Diversity, and Similarity among Multiple Communities.” Oikos, 76(1), 5–13. doi:10.2307/3545743.

Simpson EH (1949). “Measurement of Diversity.” Nature, 163(4148), 688. doi:10.1038/163688a0.

Examples

# Entropy of each community
ent_simpson(paracou_6_abd)
# gamma entropy
ent_simpson(paracou_6_abd, gamma = TRUE)

# At 80% coverage
ent_simpson(paracou_6_abd, level = 0.8)

Description

Simpson's entropy of the neighborhood of individuals, up to a distance (Shimatani 2001).

Usage

ent_sp_simpson(
  X,
  r = NULL,
  correction = c("isotropic", "translate", "none"),
  check_arguments = TRUE
)

ent_sp_simpsonEnvelope(
  X,
  r = NULL,
  n_simulations = 100,
  alpha = 0.05,
  correction = c("isotropic", "translate", "none"),
  h0 = c("RandomPosition", "RandomLabeling"),
  global = FALSE,
  check_arguments = TRUE
)

Arguments

Value

ent_sp_simpson returns an object of class fv, see spatstat.explore::fv.object. There are methods to print and plot this class. It contains the value of the spatially explicit Simpson's entropy for each distance in r.

ent_sp_simpsonEnvelope returns an envelope object spatstat.explore::envelope. There are methods to print and plot this class. It contains the observed value of the function, its average simulated value and the confidence envelope.

References

Duranton G, Overman HG (2005). “Testing for Localisation Using Micro-Geographic Data.” Review of Economic Studies, 72(4), 1077–1106. doi:10.1111/0034-6527.00362.

Shimatani K (2001). “Multivariate Point Processes and Spatial Variation of Species Diversity.” Forest Ecology and Management, 142(1-3), 215–229. doi:10.1016/s0378-1127(00)00352-2.

Examples

# Generate a random community
X <- rspcommunity(1, size = 1000, species_number = 3)
# Calculate the entropy and plot it
autoplot(ent_sp_simpson(X))

# Generate a random community
X <- rspcommunity(1, size = 1000, species_number = 3)
# Calculate the entropy and plot it
autoplot(ent_sp_simpsonEnvelope(X, n_simulations = 10))

Description

Estimate the entropy of species from abundance or probability data. Several estimators are available to deal with incomplete sampling.

Usage

ent_tsallis(x, q = 1, ...)

## S3 method for class 'numeric'
ent_tsallis(
  x,
  q = 1,
  estimator = c("UnveilJ", "ChaoJost", "ChaoShen", "GenCov", "Grassberger", "Marcon",
    "UnveilC", "UnveiliC", "ZhangGrabchak", "naive", "Bonachela", "Holste"),
  level = NULL,
  probability_estimator = c("Chao2015", "Chao2013", "ChaoShen", "naive"),
  unveiling = c("geometric", "uniform", "none"),
  richness_estimator = c("jackknife", "iChao1", "Chao1", "rarefy", "naive"),
  jack_alpha = 0.05,
  jack_max = 10,
  coverage_estimator = c("ZhangHuang", "Chao", "Turing", "Good"),
  sample_coverage = NULL,
  as_numeric = FALSE,
  ...,
  check_arguments = TRUE
)

## S3 method for class 'species_distribution'
ent_tsallis(
  x,
  q = 1,
  estimator = c("UnveilJ", "ChaoJost", "ChaoShen", "GenCov", "Grassberger", "Marcon",
    "UnveilC", "UnveiliC", "ZhangGrabchak", "naive", "Bonachela", "Holste"),
  level = NULL,
  probability_estimator = c("Chao2015", "Chao2013", "ChaoShen", "naive"),
  unveiling = c("geometric", "uniform", "none"),
  richness_estimator = c("jackknife", "iChao1", "Chao1", "rarefy", "naive"),
  jack_alpha = 0.05,
  jack_max = 10,
  coverage_estimator = c("ZhangHuang", "Chao", "Turing", "Good"),
  gamma = FALSE,
  as_numeric = FALSE,
  ...,
  check_arguments = TRUE
)

Arguments

Details

Bias correction requires the number of individuals. See div_hill for estimators.

Entropy 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 accum_tsallis for details.

Value

A tibble with the site names, the estimators used and the estimated entropy.

References

Chao A, Gotelli NJ, Hsieh TC, Sander EL, Ma KH, Colwell RK, Ellison AM (2014). “Rarefaction and Extrapolation with Hill Numbers: A Framework for Sampling and Estimation in Species Diversity Studies.” Ecological Monographs, 84(1), 45–67. doi:10.1890/13-0133.1.

Examples

# Entropy of each community
ent_tsallis(paracou_6_abd, q = 2)
# gamma entropy
ent_tsallis(paracou_6_abd, q = 2, gamma = TRUE)

# At 80% coverage
ent_tsallis(paracou_6_abd, level = 0.8)

Description

Calculate the deformed exponential of order q.

Usage

exp_q(x, q)

Arguments

Details

The deformed exponential is the reciprocal of the deformed logarithm (Tsallis 1994), see ln_q. It 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)}$.

Value

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

References

Tsallis C (1994). “What Are the Numbers That Experiments Provide?” Química Nova, 17(6), 468–471.

Examples

curve(exp_q(x, q = 0), from = -5, to = 0, lty = 2)
curve(exp(x), from = -5, to = 0, lty= 1, add = TRUE)
curve(exp_q(x, q = 2), from = -5, to = 0, lty = 3, add = TRUE)
legend("bottomright", 
  legend = c(
    expression(exp[0](x)),
    expression(exp(x)),
    expression(exp[2](x))
  ),
  lty = c(2, 1, 3), 
  inset = 0.02
)

Description

Fit a well-known distribution to a species distribution.

Usage

fit_rac(x, ...)

## S3 method for class 'numeric'
fit_rac(
  x,
  distribution = c("lnorm", "lseries", "geom", "bstick"),
  ...,
  check_arguments = TRUE
)

## S3 method for class 'species_distribution'
fit_rac(
  x,
  distribution = c("lnorm", "lseries", "geom", "bstick"),
  ...,
  check_arguments = TRUE
)

Arguments

Details

abundances can be used to fit rank-abundance curves (RAC) of classical distributions:

• "lnorm" for log-normal (Preston 1948).

• "lseries" for log-series (Fisher et al. 1943).

• "geom" for geometric (Motomura 1932).

• "bstick" for broken stick (MacArthur 1957). It has no parameter, so the maximum abundance is returned.

Value

A tibble with the sites and the estimated distribution parameters.

References

Fisher RA, Corbet AS, Williams CB (1943). “The Relation between the Number of Species and the Number of Individuals in a Random Sample of an Animal Population.” Journal of Animal Ecology, 12, 42–58. doi:10.2307/1411.

MacArthur RH (1957). “On the Relative Abundance of Bird Species.” Proceedings of the National Academy of Sciences of the United States of America, 43(3), 293–295. doi:10.1073/pnas.43.3.293, 89566.

Motomura I (1932). “On the statistical treatment of communities.” Zoological Magazine, 44, 379–383.

Preston FW (1948). “The Commonness, and Rarity, of Species.” Ecology, 29(3), 254–283. doi:10.2307/1930989.

Examples

fit_rac(paracou_6_abd, distribution = "lnorm")

Description

The ordinariness of a species is the average similarity of its individuals with others (Leinster and Cobbold 2012).

Usage

fun_ordinariness(
  species_distribution,
  similarities = diag(sum(!colnames(species_distribution) %in% non_species_columns)),
  as_numeric = FALSE,
  check_arguments = TRUE
)

Arguments

Details

All species of the species_distribution must be found in the matrix of similarities if it is named. If it is not, its size must equal the number of species. Then, the order of species is assumed to be the same as that of the species_distribution.

Value

A tibble with the ordinariness of each species, or a matrix if argument as_numeric is TRUE.

References

Leinster T, Cobbold C (2012). “Measuring Diversity: The Importance of Species Similarity.” Ecology, 93(3), 477–489. doi:10.1890/10-2402.1.

Examples

fun_ordinariness(paracou_6_abd, fun_similarity(paracou_6_fundist))

# Compare with probabilities
probabilities(paracou_6_abd)
# Decrease similarities so that ordinariness is close to probability
fun_ordinariness(paracou_6_abd, fun_similarity(paracou_6_fundist, rate = 100))

Description

Transform a distance matrix into a similarity matrix (Leinster and Cobbold 2012). Similarity between two species is defined either by a negative exponential function of their distance or by the complement to 1 of their normalized distance (such that the most distant species are 1 apart).

Usage

fun_similarity(distances, exponential = TRUE, rate = 1, check_arguments = TRUE)

Arguments

Value

A similarity matrix.

References

Leinster T, Cobbold C (2012). “Measuring Diversity: The Importance of Species Similarity.” Ecology, 93(3), 477–489. doi:10.1890/10-2402.1.

Examples

# Similarity between Paracou 6 species
hist(fun_similarity(paracou_6_fundist))

Description

Calculate the deformed logarithm of order q.

Usage

ln_q(x, q)

Arguments

Details

The deformed logarithm (Tsallis 1994) 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)}$.

Value

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

References

Tsallis C (1994). “What Are the Numbers That Experiments Provide?” Química Nova, 17(6), 468–471.

Examples

curve(ln_q(1/ x, q = 0), 0, 1, lty = 2, ylab = "Logarithm", ylim = c(0, 10))
curve(log(1 / x), 0, 1, lty = 1, n =1E4, add = TRUE)
curve(ln_q(1 / x, q = 2), 0, 1, lty = 3, add = TRUE)
legend("topright", 
  legend = c(
    expression(ln[0](1/x)),
    expression(log(1/x)),
    expression(ln[2](1/x))
  ),
  lty = c(2, 1, 3), 
  inset = 0.02
 )

Description

Abundances of communities are summed according to their weights to obtain the abundances of the metacommunity.

Usage

metacommunity(x, name = "metacommunity", ...)

## S3 method for class 'matrix'
metacommunity(
  x,
  name = "metacommunity",
  weights = rep(1, nrow(x)),
  as_numeric = TRUE,
  ...,
  check_arguments = TRUE
)

## S3 method for class 'abundances'
metacommunity(
  x,
  name = "metacommunity",
  as_numeric = FALSE,
  ...,
  check_arguments = TRUE
)

Arguments

Details

The total abundance of the metacommunity is by design equal to the sum of community abundances so that the information used by diversity estimators. A consequence is that equal weights lead to a metacommunity whose species abundances are the sum of community species abundances.

If community weights are not equal then the metacommunity abundances are in general not integer. Most diversity estimators can't be applied to non-integer abundances but the knowledge of the sample coverage of each community allow "ChaoShen" and "Grassberger" estimators.

Value

An object of class abundances with a single row or a named vector if as_numeric = TRUE.

Examples

metacommunity(paracou_6_abd)

metacommunity(paracou_6_abd)

Description

A simple dataset to test diversity functions. It contains 3 species with their abundances, their distance matrix and their phylogenetic tree.

Usage

mock_3sp_abd

mock_3sp_dist

mock_3sp_tree

Format

mock_3sp_abd is a vector, mock_3sp_dist a matrix and mock_3sp_tree an object of class ape::phylo.

An object of class dist of length 3.

An object of class phylo of length 4.

Examples

mock_3sp_abd
mock_3sp_dist
plot(mock_3sp_tree)
axis(2)

Description

A community assembly. It contains number of trees per species of the plot #6 of Paracou. The plot covers 6.25 ha of tropical rainforest, divided into 4 equally-sized subplots.

Usage

paracou_6_abd

paracou_6_wmppp

Format

paracou_6_abd is an object of class abundances, which is also a tibble::tibble. Each line of the tibble is a subplot. paracou_6_wmppp is a dbmss::wmppp object, i.e. a weighted, marked planar point pattern.

An object of class wmppp (inherits from ppp) of length 6.

Details

In paracou_6_abd (a tibble), the "site" column contains the subplot number, "weight" contains its area and all others columns contain a species. Data are the number of trees above 10 cm diameter at breast height (DBH).

In paracou_6_wmppp (a point pattern), the point type is tree species and the point weight is their basal area, in square centimeters.

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

Source

Permanent data census of Paracou: https://paracou.cirad.fr/

See Also

paracou_6_taxo, paracou_6_fundist

Description

A functional distance matrix of species of the dataset paracou_6_abd. Distances were computed from a trait dataset including specific leaf area, wood density, seed mass and 95th percentile of height. Gower's metric (Gower 1971) was used to obtain a distance matrix.

Usage

paracou_6_fundist

Format

A matrix.

Details

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

Source

Permanent data census of Paracou: https://paracou.cirad.fr/

References

Gower JC (1971). “A General Coefficient of Similarity and Some of Its Properties.” Biometrics, 27(4), 857–871. doi:10.2307/2528823.

See Also

paracou_6_abd, paracou_6_taxo

Description

The taxonomy of species of the dataset paracou_6_abd. Distances in the tree are 1 (different species of the same genus), 2 (same family) or 3 (different families).

Usage

paracou_6_taxo

Format

An object of class ape::phylo, which is a phylogenetic tree.

Details

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

Source

Permanent data census of Paracou: https://paracou.cirad.fr/

See Also

paracou_6_abd, paracou_6_fundist

Description

Methods for dendrograms of class "phylo_divent".

Usage

as_phylo_divent(tree)

is_phylo_divent(x)

Arguments

Details

as_phylo_divent calculates cuts and intervals of a phylogenetic tree and makes it available both in stats::hclust and ape::phylo formats. The conversion preprocesses the tree: it calculates cuts so that the tree can be reused efficiently by phylodiversity functions.

Value

as_phylo_divent returns a phylogenetic tree that is an object of class "phylo_divent".

Examples

# Paracou plot 6 species taxonomy
tree <- as_phylo_divent(mock_3sp_tree)
plot(tree)

Description

Plot objects of class "phylo_divent" produced by as_phylo_divent, that are phylogenetic trees.

Usage

## S3 method for class 'phylo_divent'
plot(x, ...)

Arguments

Value

NULL. Called for side effects.

Examples

# Paracou plot 6 species taxonomy
tree <- as_phylo_divent(paracou_6_taxo)
plot(tree, leaflab = "none")

Description

Plot objects of class "species_distribution" produced by species_distribution and similar functions.

Usage

## S3 method for class 'species_distribution'
plot(
  x,
  type = c("RAC", "Metacommunity"),
  ...,
  fit_rac = FALSE,
  distribution = c("lnorm", "lseries", "geom", "bstick"),
  ylog = "y",
  main = NULL,
  xlab = "Rank",
  ylab = NULL,
  palette = "Set1"
)

## S3 method for class 'species_distribution'
autoplot(
  object,
  ...,
  fit_rac = FALSE,
  distribution = c("lnorm", "lseries", "geom", "bstick"),
  ylog = TRUE,
  main = NULL,
  xlab = "Rank",
  ylab = NULL,
  pch = ggplot2::GeomPoint$default_aes$shape,
  cex = ggplot2::GeomPoint$default_aes$size
)

Arguments

Value

NULL. Called for side effects.

Description

Estimate actual probabilities of species from a sample

Usage

probabilities(x, ...)

## S3 method for class 'numeric'
probabilities(
  x,
  estimator = c("naive", "Chao2013", "Chao2015", "ChaoShen"),
  unveiling = c("none", "uniform", "geometric"),
  richness_estimator = c("jackknife", "iChao1", "Chao1", "rarefy", "naive"),
  jack_alpha = 0.05,
  jack_max = 10,
  coverage_estimator = c("ZhangHuang", "Chao", "Turing", "Good"),
  q = 0,
  as_numeric = FALSE,
  ...,
  check_arguments = TRUE
)

## S3 method for class 'abundances'
probabilities(
  x,
  estimator = c("naive", "Chao2013", "Chao2015", "ChaoShen"),
  unveiling = c("none", "uniform", "geometric"),
  richness_estimator = c("jackknife", "iChao1", "Chao1", "rarefy", "naive"),
  jack_alpha = 0.05,
  jack_max = 10,
  coverage_estimator = c("ZhangHuang", "Chao", "Turing", "Good"),
  q = 0,
  ...,
  check_arguments = TRUE
)