collector.curve: Species–area (collector's curve) function

In PhytoIn: Vegetation Analysis and Forest Inventory

Species–area (collector's curve) function

Description

Computes species accumulation (collector's) curves based on sample units (SUs). The function performs random resampling of the input matrix or data frame to estimate the expected species richness per number of SUs, with confidence intervals derived from multiple permutations.

Usage

collector.curve(
  formula,
  data,
  x,
  times = 1000,
  replace = FALSE,
  prob = 0.95,
  spar = 0,
  xlab,
  ylab,
  plot = TRUE,
  long = FALSE,
  theme = "theme_classic"
)

Arguments

formula	An optional formula specifying the relationship between taxa and sample units (e.g., Taxon ~ Sample). If provided, the function extracts variables from data. A third variable may be included to remove dead individuals (e.g., Taxon ~ Sample - Dead).
data	A data frame containing the variables specified in formula ('long format'). It must contain one column representing the sample unit labels (e.g., quadrats or points) and one column representing the taxon names of the individual plants. This argument accepts the data frame used in the argument x in phytoparam.
x	Species-by-sample matrix, with rows representing SUs and columns representing taxa ('wide format'). Can be either an abundance or presence–absence matrix. Ignored if formula and data are used.
times	Integer. Number of random permutations used in calculations. Default is 1000. Larger values (> 1000) yield more stable estimates.
replace	Logical. Indicates whether resampling is performed with replacement (TRUE, bootstrap) or without replacement (FALSE, default).
prob	Numeric. Probability level used for computing confidence intervals around species accumulation (default = 0.95).
spar	Numeric. Controls the smoothing parameter for plotted confidence intervals via spline interpolation. Default = 0 (no smoothing).
xlab	Character. Label for the x-axis in the plot. Default = "Number of samples".
ylab	Character. Label for the y-axis in the plot. Default = "Number of species".
plot	Logical. If TRUE (default), the species accumulation curve is plotted.
long	Logical. If TRUE, returns detailed results, including the full set of resampling matrices. Default = FALSE.
theme	Character string specifying the ggplot2 theme to apply (e.g., "theme_classic", "theme_bw", "theme_minimal"). Defaults to "theme_classic".

Details

Species accumulation curves are computed by sequentially adding sample units and recording species richness across permutations. Confidence intervals are estimated from the empirical distribution of resampled richness values. The plotted confidence intervals are smoothed using spline interpolation if spar > 0.

It is recommended to assign the output to an object, as the complete output (particularly with long = TRUE) can be large.

Value

If long = FALSE (default), returns a data frame with columns:

• n: number of sample units.

• s: mean number of species.

• lower: lower confidence interval bound.

• upper: upper confidence interval bound.

If long = TRUE, returns a list with:

• matrix.s: full matrix of species richness per permutation.

• s: the summarized data frame described above.

Note

With long = TRUE, the function provides access to the complete set of resampling results, useful for additional data analyses.

Author(s)

Rodrigo Augusto Santinelo Pereira [e-mail]

Adriano Sanches Melo

References

Magurran, A. E. (1988). Ecological Diversity and Its Measurement. Croom Helm.

Magurran, A. E. (2004). Measuring Biological Diversity. Blackwell Publishing.

Examples

## Using 'formula' (long format)
## Without smoothing confidence intervals
collector.curve(
  formula = Species ~ Plot - Morta,
  data = quadrat.df,
  times = 1000, long = FALSE, plot = TRUE
)

## Smoothing confidence intervals
collector.curve(
  formula = Species ~ Plot - Morta,
  data = quadrat.df,
  spar = 0.6, times = 1000, long = FALSE, plot = TRUE
)

## Using different plot themes
collector.curve(
  formula = Species ~ Plot - Morta,
  data = quadrat.df,
  times = 1000, long = FALSE, plot = TRUE, theme = "theme_light"
)
collector.curve(
  formula = Species ~ Plot - Morta,
  data = quadrat.df,
  times = 1000, long = FALSE, plot = TRUE, theme = "theme_bw"
)
collector.curve(
  formula = Species ~ Plot - Morta,
  data = quadrat.df,
  times = 1000, long = FALSE, plot = TRUE, theme = "theme_minimal"
)

## Using a matrix (wide format)
data.matrix <- with(
  quadrat.df,
  table(Plot, Species, exclude = "Morta")
)
collector.curve(x = data.matrix, times = 1000)

## Alternatively...
data.matrix <- as.matrix(
  xtabs(~ Plot + Species, data = quadrat.df, exclude = "Morta")
)
collector.curve(x = data.matrix, times = 1000)

PhytoIn documentation built on Nov. 5, 2025, 5:47 p.m.