PhytoIn (version 0.2.0)

collector.curve: 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"
)

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.

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".

Author

Rodrigo Augusto Santinelo Pereira

Adriano Sanches Melo

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.

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
)
# \donttest{
## 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)
# }