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 = c("PD", "PE", "RPE", "CE"),
  fun = "tip_shuffle",
  method = NULL,
  n_iter = 1000,
  n_rand = 100,
  summary = "quantile",
  spatial = TRUE,
  n_cores = 1,
  progress = interactive(),
  wt_row = NULL,
  wt_col = NULL,
  ...
)

Arguments

ps	phylospatial object.
metric	Character vector giving one or more diversity metrics to calculate; see ps_diversity for options. Can also specify "all" to calculate all available metrics.
fun	Null model function to use. Must be either "tip_shuffle", "nullmodel", "nullcat", "quantize", or an actual function: "tip_shuffle" (the default): 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. "nullcat": uses null model algorithms from the nullcat package. Only works with binary community data. This is the recommended path for binary data when mixing diagnostics (via ps_suggest_n_iter()) or spatial weights (via wt_row or wt_col) are desired. "quantize": uses quantize, which converts a quantitative matrix to discrete strata, applies a categorical variant of the selected null model, and then maps randomized strata back to values. Only works with quantitative (probability or abundance) community data. Any other function that accepts a community matrix as its first argument and returns a randomized version of the matrix.
method	Method used by the selected function. For fun = "nullmodel", one of the method options listed under commsim. Be sure to select a method that is appropriate to your community data_type (binary, quantitative, abundance). For fun = "nullcat" or fun = "quantize", one of the categorical algorithms listed under nullcat_methods (e.g. "curvecat", "swapcat"). Ignored if fun is "tip_shuffle" or if it is a custom function.
n_iter	Integer giving the number of swap iterations per randomized matrix. Controls how thoroughly each null matrix is mixed before sampling. Default is 1000. Used with fun = "nullcat" (passed as n_iter to nullcat), fun = "quantize" (passed to quantize_prep), and fun = "nullmodel" with sequential methods like curveball (passed as burnin to simulate.nullmodel; ignored for non-sequential vegan methods). Use ps_suggest_n_iter() to estimate an appropriate value for your dataset.
n_rand	Integer giving the number of random communities to generate.
summary	Character indicating which summary statistic to return. If "quantile", the default, the function returns the proportion of randomizations in which the observed diversity metric was greater than the randomized metric. If "zscore", it returns a "standardized effect size" or z-score relating the observed value to the mean and standard deviation of the randomizations.
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?
wt_row, wt_col	Optional square numeric weight matrices controlling which pairs of rows (sites) or columns (species) are likely to exchange values during randomization. Only used with fun = "nullcat" or fun = "quantize". Enables spatially or trait-constrained null models; e.g. a geographic distance decay matrix from ps_geodist can be used as wt_row. See nullcat for details.
...	Additional arguments passed to the selected function: quantize, nullcat, simulate.nullmodel, or a custom function. Note that the nsim argument to simulate.nullmodel should not be used here; specify n_rand instead.

Details

If ps has site weights (see the site_weight argument of phylospatial()), they are used in calculating range sizes for endemism metrics, in both the observed and the randomized communities. Note, however, that null model algorithms that randomize the community matrix preserve taxon totals across sites, not weighted range sizes. With unequal site weights, a randomized taxon can therefore have a larger or smaller range size than the observed taxon, depending on which sites it is moved into, so null distributions of endemism metrics do not hold range sizes fixed. The default "tip_shuffle" method is not affected, since it moves intact terminal ranges among taxa.

Value

A matrix with a row for every row of x, a column for every metric specified in metric, and values for the summary statistic. Or if spatial = TRUE, a sf or SpatRaster object containing these data.

See Also

ps_diversity(), ps_geodist()

Examples

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

# using the `quantize` function with the `curvecat` algorithm
if(requireNamespace("nullcat")){
    rand <- ps_rand(ps,
      fun = "quantize", method = "curvecat",
      transform = sqrt, n_strata = 4, fixed = "cell")
}

# binary data with nullcat's curvecat algorithm
ps2 <- ps_simulate(data_type = "binary")
if(requireNamespace("nullcat")){
    rand <- ps_rand(ps2, fun = "nullcat", method = "curvecat", n_iter = 1000)
}

# spatially constrained randomization using geographic distance weights
if(requireNamespace("nullcat")){
    geo <- as.matrix(ps_geodist(ps2))
    W <- exp(-geo / median(geo))
    rand <- ps_rand(ps2, fun = "nullcat", method = "curvecat",
                    n_iter = 1000, wt_row = W)
}

# using binary data, with a vegan `nullmodel` algorithm
rand <- ps_rand(ps2, "PD", "nullmodel", "r2")

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

phylospatial documentation built on Oct. 23, 2026, 1:06 a.m.