run_regional-methods: Region of Interest Based MVPA Analysis

In bbuchsbaum/rMVPA: Multivoxel Pattern Analysis in R

Region of Interest Based MVPA Analysis

Description

Run a separate MVPA analysis for multiple disjoint regions of interest.

Usage

run_regional(model_spec, region_mask, ...)

run_regional_base(
  model_spec,
  region_mask,
  coalesce_design_vars = FALSE,
  processor = NULL,
  verbose = FALSE,
  compute_performance = model_spec$compute_performance,
  return_predictions = model_spec$return_predictions,
  return_fits = model_spec$return_fits,
  ...
)

## Default S3 method:
run_regional(model_spec, region_mask, ...)

## S3 method for class 'mvpa_model'
run_regional(
  model_spec,
  region_mask,
  coalesce_design_vars = FALSE,
  processor = NULL,
  verbose = FALSE,
  ...
)

## S3 method for class 'rsa_model'
run_regional(
  model_spec,
  region_mask,
  return_fits = FALSE,
  compute_performance = TRUE,
  coalesce_design_vars = FALSE,
  ...
)

## S3 method for class 'vector_rsa_model'
run_regional(
  model_spec,
  region_mask,
  return_fits = FALSE,
  compute_performance = TRUE,
  coalesce_design_vars = FALSE,
  processor = NULL,
  verbose = FALSE,
  ...
)

Arguments

model_spec	A mvpa_model instance containing the model specifications
region_mask	A NeuroVol or NeuroSurface object where each region is identified by a unique integer
...	Extra arguments passed to specific regional analysis methods (e.g., 'return_fits', 'compute_performance').
coalesce_design_vars	If TRUE, merges design variables into the prediction table (if present and generated). Default is FALSE.
processor	An optional custom processor function for each region (ROI). If NULL (default), behavior depends on the model_spec class.
verbose	If TRUE, print progress messages during iteration (default is FALSE).
compute_performance	Logical indicating whether to compute performance metrics (default TRUE).
return_predictions	Logical indicating whether to combine a full prediction table (defaults to model_spec$return_predictions).
return_fits	Logical indicating whether to return the fitted models (default FALSE).

Details

This function serves as the base implementation for regional analyses, orchestrating data preparation, iteration over regions, performance computation, and result aggregation. Specific 'run_regional' methods for different model classes may call this function or provide specialized behavior.

This is the fallback method called when no specialized 'run_regional' method is found for the class of 'model_spec'. It typically calls 'run_regional_base'.

This method provides the standard regional analysis pipeline for objects of class 'mvpa_model' by calling 'run_regional_base'.

For ‘rsa_model' objects, 'return_predictions' defaults to 'FALSE' as standard RSA typically doesn’t produce a prediction table in the same way as classification/regression models.

For 'vector_rsa_model' objects, 'return_predictions' defaults to 'FALSE' in 'run_regional_base'. If 'model_spec$return_predictions' is TRUE, this method will assemble an 'observation_scores_table'.

Value

A regional_mvpa_result object (list) containing:

performance_table	A tibble of performance metrics for each region (if computed).
prediction_table	A tibble with detailed predictions for each observation/region (if generated).
vol_results	A list of volumetric maps representing performance metrics across space (if computed).
fits	A list of fitted model objects for each region (if requested via 'return_fits=TRUE').
model_spec	The original model specification object provided.

# Note: Original documentation said 'performance', clarified here.

Examples

  # Generate sample dataset (3D volume with categorical response)
  dataset <- gen_sample_dataset(
    D = c(10,10,10),       # Small 10x10x10 volume
    nobs = 100,            # 100 observations
    nlevels = 3,           # 3 classes
    response_type = "categorical",
    data_mode = "image",
    blocks = 3             # 3 blocks for cross-validation
  )
  
  # Create region mask with 5 ROIs
  region_mask <- NeuroVol(
    sample(1:5, size=length(dataset$dataset$mask), replace=TRUE),
    space(dataset$dataset$mask)
  )
  
  # Create cross-validation specification
  cval <- blocked_cross_validation(dataset$design$block_var)
  
  # Load SDA classifier (Shrinkage Discriminant Analysis)
  model <- load_model("sda_notune")
  
  # Create MVPA model
  mspec <- mvpa_model(
    model = model,
    dataset = dataset$dataset,
    design = dataset$design,
    model_type = "classification",
    crossval = cval,
    return_fits = TRUE    # Return fitted models
  )
  
  # Run regional analysis
  results <- run_regional(mspec, region_mask)
  
  # Access results
  head(results$performance)           # Performance metrics
  head(results$prediction_table)      # Predictions
  first_roi_fit <- results$fits[[1]]  # First ROI's fitted model

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