Community Overlap Calculation

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.

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.

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.

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

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))
#> [1] 0.08380215