View source: R/Ostats_multivariate.R

Ostats_multivariate | R Documentation |

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.

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 )

`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 |

`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 |

`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_set_args` |
additional arguments to pass to |

`verbose` |
If |

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.

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

`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 |

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.

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

Embedding an R snippet on your website

Add the following code to your website.

For more information on customizing the embed code, read Embedding Snippets.