Skip to contents

Compute Cross-Validated Condition Means within a Searchlight

Source: R/compute_cv_means.R
compute_crossvalidated_means_sl.Rd

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

if (FALSE) { # \dontrun{
  # See vignette for cross-validated mean computation
} # }