ps_quantize: Stratified randomization of a phylospatial object

In phylospatial: Spatial Phylogenetic Analysis

Stratified randomization of a phylospatial object

Description

Generates a randomized version of a phylospatial object by extracting the tip community matrix, permuting it using nullcat::quantize(), and rebuilding the phylospatial object using the permuted tip matrix.

Usage

ps_quantize(ps, wt_row = NULL, wt_col = NULL, ...)

Arguments

ps	Object of class phylospatial
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. Enables spatially constrained or functional-group constrained null models; e.g. a geographic distance decay matrix from ps_geodist can be transformed and used as wt_row. See nullcat for details. If left unspecified (the default), gives unweighted randomization.
...	Additional arguments passed to quantize, such as method, n_strata, transform, fixed, n_iter, etc.

Details

The nullcat quantize routine involves three steps: converting a quantitative matrix to categorical strata, permuting the resulting categorical matrix using one of several categorical null model algorithms, and mapping the randomized categories back to quantitative values. Supply arguments via ... to control options for each of these stages.

For repeated randomizations to generate a null distribution, it is more efficient to use ps_rand(fun = "quantize"), which is structured to avoid unnecessarily recomputing overhead that is shared across randomizations.

Value

A randomized version of ps

See Also

ps_rand(), ps_geodist()

Examples

if (requireNamespace("nullcat", quietly = TRUE)) {
  ps <- ps_simulate(data_type = "prob")
  ps_rand <- ps_quantize(ps, n_strata = 4,
    n_iter = 1000,
    method = "curvecat", fixed = "cell")

  # spatially constrained randomization
  geo <- as.matrix(ps_geodist(ps))
  W <- exp(-geo / median(geo))
  ps_rand <- ps_quantize(ps, n_strata = 4,
    n_iter = 1000,
    method = "curvecat", fixed = "cell",
    wt_row = W)
}

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