Apply a whitening plan to design and data matrices

Usage

whiten_apply(
  plan,
  X,
  Y,
  runs = NULL,
  run_starts = NULL,
  censor = NULL,
  parcels = NULL,
  inplace = FALSE,
  parallel = TRUE
)

Arguments

plan: Whitening plan from fit_noise().
X: Numeric matrix of predictors (time x regressors).
Y: Numeric matrix of data (time x voxels).
runs: Optional run labels, one per row. Each label must occupy one contiguous block and may not be missing.
run_starts: Optional 0-based run start indices (alternative to runs).
censor: Optional censored timepoints: 1-based indices or a logical mask of length nrow(Y). The filter restarts (with exact stationary initialisation when the plan uses exact_first) at the first frame after each censored one. When omitted and the plan was fitted on data with the same number of timepoints, the plan's own censor set is used.
parcels: Optional parcel labels (length = ncol(Y)) when using parcel plans.
inplace: Deprecated and ignored. The inputs were never modified (R's copy-on-modify semantics prevent it safely), so TRUE only made the result invisible. Supplying it now warns; it will be removed in a future release.
parallel: Use OpenMP parallelism if available. The thread count can be capped with options(fmriAR.max_threads = k).

Value

List with whitened data. Parcel plans return X_by per parcel; others return a single X matrix. When censoring is in effect the list also carries censor, the censored row indices. Those rows are still present in X/Y (filtered from the preceding history) and should be dropped before fitting, e.g. lm.fit(out$X[-out$censor, ], out$Y[-out$censor, ]).

Examples

# Create example design matrix and data
n_time <- 200
n_pred <- 3
n_voxels <- 50
X <- matrix(rnorm(n_time * n_pred), n_time, n_pred)
Y <- X %*% matrix(rnorm(n_pred * n_voxels), n_pred, n_voxels) +
     matrix(rnorm(n_time * n_voxels), n_time, n_voxels)

# Fit noise model from residuals
residuals <- Y - X %*% solve(crossprod(X), crossprod(X, Y))
plan <- fit_noise(residuals, method = "ar", p = 2)

# Apply whitening
whitened <- whiten_apply(plan, X, Y)
Xw <- whitened$X
Yw <- whitened$Y