community_overlap: Community Overlap Calculation

In Ostats: O-Stats, or Pairwise Community-Level Niche Overlap Statistics

Community Overlap Calculation

Description

This function calculates the median or mean of pairwise overlaps between density estimates of trait distributions of all species within a community, which can be weighted by species abundances.

Usage

community_overlap(
  traits,
  sp,
  discrete = FALSE,
  circular = FALSE,
  normal = TRUE,
  output = "median",
  weight_type = "hmean",
  randomize_weights = FALSE,
  unique_values = NULL,
  raw = FALSE,
  circular_args = list(),
  density_args = list(),
  hypervolume_set_args = list()
)

Arguments

traits	a vector of trait measurements in the univariate case, or a matrix in the multivariate case where each column is a trait.
sp	a vector with length equal to length(traits) that indicates the taxon of each individual.
discrete	whether trait data may take continuous or discrete values. Defaults to FALSE (all traits continuous). A single logical value or a logical vector with length equal to the number of columns in traits.
circular	whether trait data are circular (e.g., hours or angles). Defaults to FALSE (all traits non-circular). A single logical value or a logical vector with length equal to the number of columns in traits.
normal	if TRUE, the area under all density functions is normalized to 1, if FALSE, the area under all density functions is proportional to the number of observations in that group.
output	specifies whether median or mean is calculated.
weight_type	specifies weights to be used to calculate the median or mean.
randomize_weights	If TRUE, randomize weights given to pairwise overlaps within a community. This can be used to generate null models.
unique_values	Vector of all possible discrete values that traits can take. Only used if discrete = TRUE and circular = TRUE.
raw	If TRUE, also return the raw individual pairwise overlaps used to calculate the community-level statistic. Default is FALSE.
circular_args	optional list of additional arguments to pass to circular. Only used if circular = TRUE and discrete = FALSE.
density_args	list of additional arguments to be passed to density if univariate, or hypervolume if multivariate.
hypervolume_set_args	list of additional arguments to be passed to hypervolume_set. Used only in multivariate case.

Details

The function evaluates weighted mean or median of overlaps of density estimates of all species in a community taking complete cases with species abundances greater than 1 from the dataset. The default calculates the median of pairwise overlaps for the whole community using the harmonic means of abundances of the species pairs as weights, which minimizes the effect of outliners and rare species.If the argument weight_type = "none", no weights are used for the calculation of mean/median. If weight_type = "mean", arithmetic means of abundances are used as weights. To change the output to mean, specify the argument output = "mean".

Value

The function returns the O-statistic for the community as a numeric value. If raw = TRUE, instead a list is returned, where the first element value is the numeric value, and the second element raw is a data frame with all the raw pairwise overlaps.

References

Read, Q. D. et al. Among-species overlap in rodent body size distributions predicts species richness along a temperature gradient. Ecography 41, 1718-1727 (2018).

Examples

# Keep only the relevant part of small mammal data
dat <- small_mammal_data[small_mammal_data$siteID %in% c('HARV','JORN'), ]
dat <- dat[!is.na(dat$weight), ]
dat$log_weight <- log10(dat$weight)

# Calculate median of pairwise overlaps for the community,weighted by harmonic means
# of abundances
community_overlap(traits = as.matrix(dat$log_weight),
   sp = factor(dat$taxonID))

Ostats documentation built on Sept. 12, 2022, 5:05 p.m.