# Ostats_multivariate: Calculate multivariate O-statistics In Ostats: O-Stats, or Pairwise Community-Level Niche Overlap Statistics

 Ostats_multivariate R Documentation

## Calculate multivariate O-statistics

### Description

This function calculates a single O-statistic across multiple traits by estimating hypervolumes for each species in multivariate trait space that contain the trait values for all the individuals in each species. It uses a stochastic estimation procedure implemented in the R package hypervolume. The community-level O-statistics estimated from the hypervolume overlaps can be evaluated against a null model.

### Usage

```Ostats_multivariate(
traits,
plots,
sp,
output = "median",
weight_type = "hmean",
run_null_model = TRUE,
nperm = 99,
nullqs = c(0.025, 0.975),
shuffle_weights = FALSE,
swap_means = FALSE,
random_seed = NULL,
hypervolume_args = list(),
hypervolume_set_args = list(),
verbose = FALSE
)
```

### Arguments

 `traits` matrix of trait measurements. The number of rows in the matrix is the number of individuals, and the number of columns of the matrix is the number of traits. `plots` a factor with length equal to nrow(traits) that indicates the community each individual belongs to. `sp` a factor with length equal to nrow(traits) that indicates the taxon of each individual. `output` specifies whether median or mean is calculated. `weight_type` specifies weights to be used to calculate the median or mean. `run_null_model` whether to run a null model (if `TRUE`) and evaluate the O-statistics against it, or simply return the raw O-statistics (if `FALSE`). Defaults to `TRUE`. `nperm` the number of null model permutations to generate. Defaults to 99. `nullqs` numeric vector of probabilities with values in [0,1] to set effect size quantiles. Defaults to `c(0.025, 0.975)`. `shuffle_weights` If TRUE, shuffle weights given to pairwise overlaps within a community when generating null models. `swap_means` If TRUE, swap means of body sizes within a community when generating null models. `random_seed` User may supply a random seed to enable reproducibility of null model output. A warning is issued, and a random seed is generated based on the local time, if the user does not supply a seed. `hypervolume_args` additional arguments to pass to `hypervolume`, such as `method`. If none are provided, default values are used. By default, `method = "gaussian"`. `hypervolume_set_args` additional arguments to pass to `hypervolume_set`, such as `num.points.max`. If none are provided, default values are used. `verbose` If `TRUE`, progress messages are displayed. Defaults to `FALSE`.

### Details

This function calculates multivariate O-statistics and optionally evaluates them against a local null model. By default, it calculates the median of pairwise hypervolume overlaps, weighted by harmonic mean of species abundaces of the species pairs in each community. Two results are produced, one normalizing the area under all density functions to 1, the other making the area under all density functions proportional to the number of observations in that group.

Functions from the R package hypervolume by Blonder and colleagues (Blonder 2018) are used internally. The function `hypervolume` stochastically estimates hypervolumes for each species in each community, and the function `hypervolume_set` finds the proportional overlap between each pair of hypervolumes.

If `run_null_model` is `TRUE`, the O-statistics are evaluated relative to a null model. When both `shuffle_weights` and `swap_means` are `FALSE`, null communities are generated by randomly assigning a taxon that is present in the community to each individual. If `shuffle_weights` is `TRUE`, species abundances are also randomly assigned to each species to weight the O-statistic for each null community. If `swap_means` is `TRUE`, instead of sampling individuals randomly, species means are sampled randomly among species, keeping the deviation of each individual from its species mean the same. After the null communities are generated, O-stats are calculated for each null community to compare with the observed O-stat.

Effect size statistics are calculated by z-transforming the O-statistics using the mean and standard deviation of the null distribution.

### Value

The function returns a list containing four objects:

 `overlaps_norm` a matrix showing the O-statistic for each community, with the area under all density functions normalized to 1. `overlaps_unnorm` a matrix showing O-stats calculated with the area under all density functions proportional to the number of observations in that group. `overlaps_norm_ses` List of matrices of effect size statistics against a null model with the area under all density functions normalized to 1. `ses` contains the effect sizes (z-scores), `ses_lower` contains the effect size lower critical values for significance at the level determined by `nullqs`, and `ses_upper` contains the upper critical values. `raw_lower` and `raw_upper` are the critical values in raw units ranging from 0 to 1. `overlaps_unnorm_ses` List of matrices of effect size statistics against a null model with the area under all density functions proportional to the number of observations in that group. Elements are as in `overlaps_norm_ses`.

### References

Blonder, B. Hypervolume concepts in niche- and trait-based ecology. Ecography 41, 1441–1455 (2018). https://doi.org/10.1111/ecog.03187

`Ostats` for univariate data.

`Ostats_multivariate_plot` for plotting multivariate trait overlap in each community.

### Examples

```## Not run:
# overlap statistic between populations of pitcher plants at two different sites

# Select two sites and three dimensions and scale data
site_index <- pitcher_traits[, 'site_id'] %in% c('FLK', 'MYR')
dat <- as.matrix(pitcher_traits[site_index,
c('rosette_diameter_1', 'pitcher_width', 'mouth_diameter')])
dat <- scale(dat, center = TRUE, scale = TRUE)

# Here a low number is used for num.points.max for example purposes
Ostats_multi_example <- Ostats_multivariate(traits = dat,
plots = factor(rep(1, nrow(dat))),
sp = factor(pitcher_traits\$site_id[site_index]),
random_seed = 111,
run_null_model = FALSE,
hypervolume_args = list(method = 'box'),
hypervolume_set_args = list(num.points.max = 100)
)

## End(Not run)

```

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