run_searchlight.contrast_rsa_model: Run Searchlight Analysis for Contrast RSA Model

In bbuchsbaum/rMVPA: Multivoxel Pattern Analysis in R

Run Searchlight Analysis for Contrast RSA Model

Description

This is the S3 method for running a searchlight analysis specifically for a contrast_rsa_model object. It performs the Multi-Dimensional Signed Representational Voxel Encoding (MS-ReVE) style analysis across the brain volume or surface.

Usage

## S3 method for class 'contrast_rsa_model'
run_searchlight(
  model_spec,
  radius = NULL,
  method = c("standard", "randomized"),
  niter = NULL,
  ...
)

Arguments

model_spec	A contrast_rsa_model object created by \link{contrast_rsa_model}.
radius	The radius of the searchlight sphere (in mm for volume data, or geodesic distance/vertex count for surface data - interpretation depends on the distance_metric used in neuroim2::searchlight or neurosurf::SurfaceSearchlight).
method	The type of searchlight procedure. Currently, only "standard" is fully supported and recommended for contrast RSA. The "standard" method iterates through all voxels/vertices in the mask, treating each as the center and calculating its specific contribution metric (e.g., beta_delta). The results are combined directly into Q output maps using combine_msreve_standard. Using "randomized" is **not recommended** for this model. While the code will run, the default combiner (combine_msreve_standard) will produce sparse maps with values only at the random center locations. A proper interpretation of randomized searchlight (averaging results based on voxel coverage) would require a different, model-specific combiner (e.g., combine_msreve_randomized), which is not currently implemented due to conceptual challenges in averaging the center-voxel specific MS-ReVE metric.
niter	The number of iterations if method = "randomized" is used (but see note above).
...	Additional arguments passed down to the underlying searchlight machinery (e.g., mvpa_iterate).

Value

A searchlight_result object (specifically with class c("msreve_searchlight_result", "searchlight_result", "list")), containing:

results	A named list where each element is a SparseNeuroVec or NeuroSurfaceVector representing the map for one contrast.
metrics	A character vector of the contrast names.
n_voxels	Total number of voxels/vertices in the original mask space.
active_voxels	Number of voxels/vertices for which results were computed.

Examples

# Assuming 'spec' is a valid contrast_rsa_model object
# Standard (recommended) method:
# results <- run_searchlight(spec, radius = 8, method = "standard")
# plot(results$results[[1]]) # Plot the map for the first contrast

# Assuming contrast_rsa_model examples have run and objects like
# 'mvpa_dat', 'msreve_des', 'model_basic', 'model_recon' are available.
# This requires the setup from contrast_rsa_model examples.

if (requireNamespace("neuroim2", quietly = TRUE) && 
    requireNamespace("rMVPA", quietly = TRUE) &&
    exists("model_basic") && inherits(model_basic, "contrast_rsa_model") &&
    exists("model_recon") && inherits(model_recon, "contrast_rsa_model")) {

  # --- Example 1: Run searchlight with basic model ---
  # Use a very small radius for quick example run.
  # Actual searchlight analyses would use a more appropriate radius (e.g., 3-4 voxels).
  # With dummy data, results won't be meaningful; focus is on execution.

  message("Running searchlight example 1 (basic model, radius=1)... May take a moment.")
  sl_results_basic <- tryCatch({
    run_searchlight(model_basic, radius = 1, method = "standard")
  }, error = function(e) {
    message("Searchlight (basic model) example failed: ", e$message)
    NULL
  })
  if (!is.null(sl_results_basic)) {
    print(sl_results_basic)
  }

  # --- Example 2: Run searchlight with recon_score output ---
  message("Running searchlight example 2 (recon_score model, radius=1)... May take a moment.")
  sl_results_recon <- tryCatch({
    run_searchlight(model_recon, radius = 1, method = "standard")
  }, error = function(e) {
    message("Searchlight (recon_score model) example failed: ", e$message)
    NULL
  })
  if (!is.null(sl_results_recon)) {
    print(sl_results_recon)
  }

  # Note on Crossnobis with searchlight:
  # To run a searchlight with 'estimation_method = "crossnobis"' from 'model_crossnobis',
  # the 'whitening_matrix_W' needs to be passed through the searchlight machinery
  # to 'compute_crossvalidated_means_sl'. This typically involves passing it via
  # the `...` argument of `run_searchlight` and ensuring `mvpa_iterate` and
  # `train_model` propagate it. This advanced usage is not shown here as it
  # requires modification to the general `mvpa_iterate` or a custom processor.

} else {
 message("Skipping run_searchlight.contrast_rsa_model example execution here.")
 message("It can be time-consuming and depends on prior setup.")
}

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