ps_rand: Null model randomization analysis of alpha diversity metrics

In phylospatial: Spatial Phylogenetic Analysis

Null model randomization analysis of alpha diversity metrics

Description

This function compares phylodiversity metrics calculated in ps_diversity to their null distributions computed by randomizing the community matrix or shuffling the tips of the phylogeny, indicating statistical significance under the assumptions of the null model. Various null model algorithms are available for binary, probability, and count data.

Usage

ps_rand(
  ps,
  metric = "all",
  fun = "quantize",
  method = "curveball",
  n_rand = 100,
  spatial = TRUE,
  n_cores = 1,
  progress = interactive(),
  ...
)

Arguments

ps	phylospatial object.
metric	Character vector giving one or more diversity metrics to calculate; see ps_diversity for options. Can also specify "all" (the default) to calculate all available metrics.
fun	Null model function to use. Must be either "tip_shuffle", "nullmodel", "quantize", or an actual function: "tip_shuffle": randomly shuffles the identities of terminal taxa "nullmodel": uses nullmodel and simulate.nullmodel, from the vegan package, which offer a wide range of randomization algorithms with different properties. "quantize": (the default) deploys the function quantize, a routine that is itself a wrapper around nullmodel, allowing the use of binary algorithms for quantitative data. Any other function that accepts a community matrix as its first argument and returns a randomized version of the matrix.
method	One of the method options listed under commsim. If fun = "quantize", this must be one of the "binary" methods. If fun = "nullmodel", be sure to select a method that is appropriate to your community data_type (binary, quantitative, abundance). This argument is ignored if fun is "tip_shuffle" or if it is a custom function.
n_rand	Integer giving the number of random communities to generate.
spatial	Logical: should the function return a spatial object (TRUE, default) or a matrix (FALSE).
n_cores	Integer giving the number of compute cores to use for parallel processing.
progress	Logical: should a progress bar be displayed?
...	Additional arguments passed to quantize, simulate.nullmodel, or custom function fun. Note that the nsim argument the former two functions should not be used here; specify n_rand instead.

Value

A matrix with a row for every row of x, a column for every metric specified in metric, and values indicating the proportion of randomizations in which the observed diversity metric was greater than the randomized metric. Or if spatial = TRUE, a sf or SpatRaster object containing these data.

See Also

ps_diversity()

Examples

# simulate a `phylospatial` data set and run randomization with default settings
ps <- ps_simulate(data_type = "prob")
rand <- ps_rand(ps)

# using the default `quantize` function, but with alternative arguments
rand <- ps_rand(ps, transform = sqrt, n_strata = 4, priority = "rows")

# using binary data
ps2 <- ps_simulate(data_type = "binary")
rand <- ps_rand(ps2, fun = "nullmodel", method = "r2")

# using abundance data, and demonstrating alternative metric choices
ps3 <- ps_simulate(data_type = "abund")
rand <- ps_rand(ps3, metric = c("ShPD", "SiPD"), fun = "nullmodel", method = "abuswap_c")
rand

phylospatial documentation built on April 12, 2025, 1:35 a.m.