Runs multiple independent chains of the null model randomization algorithm and
records a mixing diagnostic at each step, producing trace plots to assess convergence.
This is a convenience wrapper around nullcat::trace_cat() that extracts the
appropriate community matrix from a phylospatial object.
Usage
ps_trace(
ps,
fun = c("nullcat", "quantize"),
plot = TRUE,
site_groups = NULL,
...
)Arguments
- ps
A
phylospatialobject.- fun
Character:
"nullcat"or"quantize", matching the intendedfunargument tops_rand().- plot
Logical: if
TRUE, plot the traces.- site_groups
Optional grouping of sites, as passed to
ps_rand(). Randomizations then run independently within groups, withn_iterapplied to each group. The trace runs the grouped randomization as a whole (using the first column of a matrix of groupings), so the result estimates then_iterneeded per group, which can be more or fewer than the full matrix needs. Use the samesite_groups(e.g. tilings fromps_tile_groups()with the samespacing) as in the intendedps_rand()call. Each traced chain costs as much as one grouped randomization ofn_iteriterations.- ...
Additional arguments passed to
nullcat::trace_cat(), such asmethod,n_iter,thin,n_chains,n_strata,fixed,stat, etc.
Value
An object of class "cat_trace". See nullcat::trace_cat() for details.
Examples
# \donttest{
if (requireNamespace("nullcat", quietly = TRUE)) {
ps_bin <- ps_simulate(data_type = "binary")
tr <- ps_trace(ps_bin, fun = "nullcat", method = "curvecat",
n_iter = 2000, n_chains = 5, plot = TRUE)
ps <- ps_simulate(data_type = "prob")
tr <- ps_trace(ps, fun = "quantize", method = "curvecat",
n_strata = 4, fixed = "cell",
n_iter = 2000, n_chains = 5, plot = TRUE)
}
#> Warning: 61 of 400 rows and 0 of 10 columns have all their values in a single stratum, so the randomization cannot change them under `fixed = "cell"`: their randomized values will equal the observed values. To randomize them, separate low values into their own strata (e.g. `zero_stratum = TRUE`, or a `transform`), or use a different `fixed` mode.
# }
