Compute Cross-Validated Condition Means within a Searchlight

This helper function calculates the mean activation pattern for each condition using data from other cross-validation folds.

Usage

compute_crossvalidated_means_sl(
  sl_data,
  mvpa_design,
  cv_spec,
  estimation_method = "average",
  whitening_matrix_W = NULL,
  return_folds = FALSE
)

Arguments

sl_data

A numeric matrix (samples x voxels/vertices) containing the data for the current searchlight.

mvpa_design

The mvpa_design object associated with the dataset, containing condition labels and block information.

cv_spec

An object describing the cross-validation scheme, typically created by functions like \link{blocked_cross_validation}, \link{twofold_blocked_cross_validation}, \link{kfold_cross_validation}, etc. (inheriting from cross_validation). This object determines how training/test folds are defined.

estimation_method

Character string specifying the method to estimate means. Currently supported: "average" (simple mean of training samples per condition).

• "average": Simple mean of training samples per condition.

• "L2_norm": Identical to "average" but each condition pattern (row) is finally scaled to unit L2 norm. Useful when you need to equalise overall pattern energy across conditions before RSA.

• "crossnobis": Computes independent partition-wise condition means for crossnobis distances/second moments. If `whitening_matrix_W` is supplied, each partition mean is whitened before being returned/averaged; if it is `NULL`, raw Euclidean patterns are used.

Default is "average".

whitening_matrix_W

Optional V x V numeric matrix, where V is the number of voxels/features in `sl_data`. This matrix should be the whitening transformation (e.g., Sigma_noise^(-1/2)) derived from GLM residuals. If comparing to implementations that accept a precision matrix P directly, use W such that W %*% t(W) = P (for example, `t(chol(P))` for a positive-definite precision matrix). Used only if `estimation_method = "crossnobis"`. If `NULL`, no whitening is applied.

return_folds

Logical, if TRUE, the function returns a list containing both the overall mean estimate (`mean_estimate`) and an array of per-fold estimates (`fold_estimates`). If FALSE (default), only the overall mean estimate is returned.

Value

If `return_folds = FALSE` (default): A numeric matrix (K x V_sl) where K is the number of conditions and V_sl is the number of voxels/vertices in the searchlight. Each row represents the cross-validated mean pattern for condition k. If `return_folds = TRUE`: A list with two elements:

`mean_estimate`

The K x V_sl matrix described above.

`fold_estimates`

A K x V_sl x M array, where M is the number of folds, containing the mean estimate for each condition from each fold.

Examples

# 4 conditions x 3 runs, 12 voxels
des_df <- data.frame(cond = factor(rep(c("a", "b", "c", "d"), times = 6)),
                     run  = rep(1:3, each = 8))
mvdes <- mvpa_design(des_df, y_train = ~ cond, block_var = ~ run)
cv <- blocked_cross_validation(des_df$run)
sl_data <- matrix(rnorm(nrow(des_df) * 12), nrow(des_df), 12)
U <- compute_crossvalidated_means_sl(sl_data, mvdes, cv,
                                     estimation_method = "average")
dim(U)
#> [1]  4 12