In bbuchsbaum/rMVPA: Multivoxel Pattern Analysis in R

suppressPackageStartupMessages({
  library(neuroim2)
  library(rMVPA)
})

Introduction

contrast_rsa_model() implements the Multi-Dimensional Signed Representational Voxel Encoding (MS-ReVE) approach. It relates voxel patterns to a set of predefined contrasts and produces maps that summarize how each contrast contributes to the local representational geometry.

This vignette walks through a minimal example and explains the available output metrics.

Example setup

We start by generating a small example dataset and defining two contrasts. The contrasts should be column centered so that positive values indicate conditions that pull voxels in one direction and negative values pull in the opposite direction.

# Generate dummy dataset (small 6x6x6 volume, 32 samples)
set.seed(42)
data_info <- gen_sample_dataset(D = c(6,6,6), nobs = 32, blocks = 4)

# mvpa_dataset object
mvpa_dat <- data_info$dataset

# Design with two simple contrasts across four conditions
K <- data_info$design$ncond
C_mat <- matrix(0, nrow = K, ncol = 2)
rownames(C_mat) <- levels(data_info$design$Y)
C_mat[1:2,1] <- 1; C_mat[3:4,1] <- -1
C_mat[1,2] <- 1; C_mat[2,2] <- -1
C_mat <- scale(C_mat, center = TRUE, scale = FALSE)
colnames(C_mat) <- c("AB_vs_CD", "A_vs_B")

ms_des <- msreve_design(mvpa_dat$design, contrast_matrix = C_mat)

Next we create the model specification and run a tiny searchlight over the volume. Here we request two output metrics: the default "beta_delta" and the optional "recon_score".

model_spec <- contrast_rsa_model(
  dataset = mvpa_dat,
  design = ms_des,
  output_metric = c("beta_delta", "recon_score"),
  check_collinearity = FALSE
)

# Run a very small searchlight just for demonstration
sl_result <- run_searchlight(
  model_spec,
  radius = 2,
  method = "standard"
)

# Inspect the returned metrics for the first few voxels
head(sl_result$results[, c("beta_delta", "recon_score")])

Understanding the output metrics

contrast_rsa_model can return several metrics. Multiple metrics can be requested at once and are returned in a named list for each searchlight location. The main options are:

beta_delta

The product of the RSA regression coefficient ((\beta_q)) and the voxel's projection onto each contrast ((\Delta_{q,v})). This signed quantity indicates how strongly the voxel supports the representational difference captured by each contrast. Positive values mean the voxel pattern aligns with the predicted direction; negative values indicate the opposite.

beta_only

Only the regression coefficients (\beta_q). Useful when you want a map of how much each contrast explains the local RDM independent of the voxel projections.

delta_only

The projection values (\Delta_{q,v}) by themselves. These show the raw contribution of each voxel to the contrast space before weighting by (\beta_q).

recon_score

A single value (per voxel) measuring how well the voxel's beta-weighted pattern reconstructs the empirical RDM of the searchlight. Higher values indicate the voxel is individually informative about the multi-contrast representational structure.

beta_delta_norm

Like beta_delta but using an L2-normalized contribution vector. This emphasizes the direction of the contribution rather than its magnitude and requires normalize_delta = TRUE when constructing the model.

beta_delta_reliable

Reliability-weighted contributions (\rho_{q,v} \beta_q \Delta_{q,v}). The weights (\rho_{q,v}) reflect how stable each voxel's contributions are across cross-validation folds, highlighting consistent effects.

composite

The sum of beta-weighted, normalized contributions across contrasts ((\sum_q \beta_q \tilde{\Delta}_{q,v})). This "net pull" summarizes whether a voxel overall favors the positive or negative side of the contrast space. Interpretation is easiest when the contrast matrix is orthonormal.

These metrics allow flexible interrogation of how each voxel or region participates in the specified representational contrasts.

Conclusion

contrast_rsa_model extends standard RSA by decomposing voxel contributions along user-defined contrasts. By selecting appropriate output metrics you can visualize beta weights, raw contributions, reliability-weighted effects, or overall reconstruction quality. The combination of metrics provides a rich picture of the representational landscape revealed by the analysis.

bbuchsbaum/rMVPA documentation built on June 10, 2025, 8:23 p.m.