rarefact_space_similarity: Calculates rarefacted space overlaps

In maRce10/PhenotypeSpace: Quantifying phenotypic spaces

Calculates rarefacted space overlaps

Description

rarefact_space_similarity

Usage

rarefact_space_similarity(
  formula,
  data,
  n = NULL,
  replace = FALSE,
  seed = NULL,
  cores = 1,
  pb = TRUE,
  iterations = 30,
  ...
)

Arguments

formula	an object of class "formula" (or one that can be coerced to that class).Must follow the form group ~ dim1 + dim2 where dim1 and dim2 are the dimensions of the phenotype space and group refers to the group labels.
data	Data frame containing columns for the dimensions of the phenotypic space (numeric) and a categorical or factor column with group labels.
n	Integer vector of length 1 indicating the number of samples to be use for rarefaction (i.e. how many samples per group will be gather at each iteration). Default is the minimum sample size across groups.
replace	Logical argument to control if sampling is done with replacement. Default is FALSE.
seed	Integer vector of length 1 setting the seed (see set.seed). If used results should be the same on different runs, so it makes them replicable.
cores	Numeric vector of length 1. Controls whether parallel computing is applied by specifying the number of cores to be used. Default is 1 (i.e. no parallel computing).
pb	Logical argument to control if progress bar is shown. Default is TRUE.
iterations	Integer vector of length 1. Controls how the number of times the rarefaction routine is iterated. Default is 30.
...	Additional arguments to be passed to space_similarity for customizing similarity measurements.

Details

The function applies a rarefaction sub-sampling procedure for evaluating pairwise space similarity (internally using space_similarity). The spread and shape of a phenotypic space might change as a function of number of samples. Hence, ideally, spaces should be compared between groups of similar sample sizes. Rarefaction allows to compare groups of unbalanced sample sizes by randomly re-sampling observations using the same number samples across groups iteratively.

Value

A data frame containing the mean, minimum, maximum and standard deviation of the similarity metric across iterations for each pair of groups. If the similarity metric is not symmetric (e.g. the proportional area of A that overlaps B is not necessarily the same as the area of B that overlaps A, see space_similarity) separated columns are supplied for the two comparisons.

Author(s)

Marcelo Araya-Salas [e-mail])

References

Araya-Salas, M, & K. Odom. 2022, PhenotypeSpace: an R package to quantify and compare phenotypic trait spaces R package version 0.1.0.

See Also

space_similarity, rectangular_to_triangular

Examples

{
# load data
data("example_space")

# get proportion of space that overlaps (try with more iterations on your own data)
prop_overlaps <- rarefact_space_similarity(
 formula = group ~ dimension_1 + dimension_2,
 data = example_space,
method = "proportional.overlap", 
iterations = 5)

# get minimum convex polygon overlap for each group (non-symmetric)
mcp_overlaps <- rarefact_space_similarity(
 formula = group ~ dimension_1 + dimension_2,
 data = example_space,
 iterations = 5)

# convert to non-symmetric triangular matrix
rectangular_to_triangular(mcp_overlaps, symmetric = FALSE)
}

maRce10/PhenotypeSpace documentation built on July 3, 2025, 8:44 p.m.