Region of Interest Based MVPA Analysis — run

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).

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.

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`.

Examples

# \donttest{
  # 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)
  )
#> Error in NeuroVol(sample(1:5, size = length(dataset$dataset$mask), replace = TRUE),     space(dataset$dataset$mask)): could not find function "NeuroVol"
  
  # 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)
#> Error: object 'region_mask' not found
  
  # Access results
  head(results$performance)           # Performance metrics
#> Error: object 'results' not found
  head(results$prediction_table)      # Predictions
#> Error: object 'results' not found
  first_roi_fit <- results$fits[[1]]  # First ROI's fitted model
#> Error: object 'results' not found
# }