Generate correlated design replicates for a set of groups

Usage

sb_resample_groups(
  X_norm,
  groups,
  B = 100,
  jitter = 1e-06,
  seed = NULL,
  use.parallel = FALSE,
  cache = NULL
)

Arguments

X_norm: Normalised design matrix.
groups: Correlation structure. Either a list as returned by sb_group_variables() or a vector of group labels matching the columns of X_norm.
B: Number of replicates to generate.
jitter: Numeric value added to covariance diagonals for stability.
seed: Optional integer seed for reproducibility. The seed is scoped via withr::with_seed() so the caller's RNG state is restored on exit.
use.parallel: Logical; when TRUE, compute the resampled designs using a parallel backend when available.
cache: Optional environment or named list used to cache previously generated surrogates. Passing the same cache across calls reuses draws for identical groups.

Value

An object of class sb_resamples, i.e. a list of length B whose elements are resampled design matrices. The object exposes per-group diagnostics in its "diagnostics" attribute and returns the cache via the "cache" attribute for reuse.

Details

When every group has size one (no correlated variables) the function simply returns B copies of X_norm. A warning is issued in that situation so downstream code can avoid mistaking the replicated designs for genuinely resampled surrogates. The covariance matrices underpinning each correlated draw are cached in the supplied cache environment; reusing the environment across calls lets sb_resample_groups() skip redundant covariance decompositions for identical groups and speeds up iterative workflows.