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

 community_overlap R Documentation

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