Skip to contents

Trace diagnostics for categorical randomizations

Source: R/trace_cat.R
trace_cat.Rd

Applies nullcat() or quantize() to a community matrix, recording a summary statistic at each iteration to help assess mixing on a given dataset.

Usage

trace_cat(
  x,
  fun = c("nullcat", "quantize"),
  n_iter = 1000L,
  thin = NULL,
  n_chains = 5L,
  n_cores = 1L,
  stat = NULL,
  seed = NULL,
  plot = FALSE,
  ...
)

Arguments

x

Matrix of categorical data (integers) or quantitative values.

fun

Which function to trace: "nullcat" or "quantize".

n_iter

Total number of update iterations to simulate. Default is 1000.

thin

Thinning interval (updates per recorded point). Default ~ n_iter/100. Smaller values increase resolution but increase run time.

n_chains

Number of independent chains to run, to assess consistency (default 5).

n_cores

Parallel chains (default 1).

stat

Function that compares x to a permuted x_rand to quantify their similarity. Either a function f(x, x_rand) returning a scalar, or NULL. If NULL (the default), traces use Cohen's kappa for nullcat() or Pearson's correlation for quantize().

seed

Optional integer seed for reproducible traces.

plot

If TRUE, plot the traces.

...

Arguments to the chosen fun (nullcat() or quantize()), such as method, n_strata, fixed, etc. If row_groups and/or col_groups are supplied (as vectors, or as matrices with one column per replicate), randomizations run independently within blocks and n_iter applies to each block, so the trace is run on the single largest block (the one with the most cells, searched across up to the first 10 columns of a groups matrix), as it is generally the slowest to mix. For quantize, strata are still defined from the full matrix.

Value

An object of class "cat_trace" with elements:

  • traces: matrix of size (n_steps+1) x n_chains, including iteration 0

  • steps: integer vector of iteration numbers (starting at 0)

  • fun, n_iter, thin, n_chains, n_cores, stat_name, call

  • fun_args: list of the ... used (for reproducibility)

  • block: when groups were supplied, the dimensions of the block that was traced; otherwise NULL

Plotting is available via plot(cat_trace).

Examples

# nullcat trace
set.seed(123)
x <- matrix(sample(1:5, 2500, replace = TRUE), 50)
tr <- trace_cat(x, n_iter = 1000, n_chains = 5, fun = "nullcat",
                method = "curvecat")
plot(tr)


# quantize trace
x <- matrix(runif(2500), 50)
tr <- trace_cat(x, n_iter = 1000, n_chains = 5, fun = "quantize",
                method = "curvecat", n_strata = 3, fixed = "cell")
plot(tr)