Skip to contents

Null model randomization analysis of alpha diversity metrics

ps_rand.Rd

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

# \donttest{
# 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
#> class       : SpatRaster 
#> dimensions  : 20, 20, 2  (nrow, ncol, nlyr)
#> resolution  : 1, 1  (x, y)
#> extent      : 0, 20, 0, 20  (xmin, xmax, ymin, ymax)
#> coord. ref. :  
#> source(s)   : memory
#> varnames    : qShPD 
#>               qSiPD 
#> names       : qShPD, qSiPD 
#> min values  :  0.00,  0.00 
#> max values  :  0.03,  0.03 
# }