run_custom_regional: Run a Custom Analysis Function Regionally

In bbuchsbaum/rMVPA: Multivoxel Pattern Analysis in R

Run a Custom Analysis Function Regionally

Description

Applies a user-defined function to the data within each specified region of interest (ROI) and returns the results as a tibble.

Usage

run_custom_regional(
  dataset,
  region_mask,
  custom_func,
  ...,
  .cores = 1,
  .verbose = FALSE
)

Arguments

dataset	An 'mvpa_dataset' or 'mvpa_surface_dataset' object.
region_mask	A 'NeuroVol' or 'NeuroSurface' object where each region is identified by a unique integer greater than 0.
custom_func	A function to apply to each ROI's data. It should accept two arguments: 'roi_data': A matrix or tibble containing the data (samples x features) for the current ROI. 'roi_info': A list containing 'id' (the region number) and 'indices' (the feature indices for this ROI). The function *must* return a named list or a single-row data frame (or tibble) containing scalar metric values.
...	Optional arguments passed to 'mvpa_iterate' (e.g., 'batch_size').
.cores	Number of cores to use for parallel processing via the 'future' framework. Defaults to 1 (sequential). Set using 'future::plan()' beforehand for more control.
.verbose	Logical. If 'TRUE', prints progress messages during iteration. Defaults to 'FALSE'.

Details

This function provides a simplified interface for applying custom analyses per ROI without needing to define a full 'mvpa_model' specification or implement S3 methods. It leverages the parallel processing and iteration capabilities of 'rMVPA'.

The user-supplied 'custom_func' performs the core calculation for each ROI. The framework handles extracting data, iterating over ROIs (potentially in parallel), catching errors from 'custom_func', and formatting the output into a convenient flat table.

Value

A 'tibble' where each row corresponds to an ROI. It includes:

• 'id': The ROI identifier (region number).

• Columns corresponding to the names returned by 'custom_func'.

• 'error': Logical indicating if an error occurred for this ROI.

• 'error_message': The error message if an error occurred.

Examples

# Generate sample dataset
dset_info <- gen_sample_dataset(D = c(8,8,8), nobs = 50, nlevels = 2)
dataset_obj <- dset_info$dataset
design_obj <- dset_info$design # Not used by custom_func here, but needed for setup

# Create a region mask with 3 ROIs
mask_arr <- array(0, dim(dataset_obj$mask))
mask_arr[1:4, 1:4, 1:4] <- 1
mask_arr[5:8, 1:4, 1:4] <- 2
mask_arr[1:4, 5:8, 5:8] <- 3
region_mask_vol <- NeuroVol(mask_arr, space(dataset_obj$mask))

# Define a custom function: calculate mean and sd for each ROI
my_roi_stats <- function(roi_data, roi_info) {
  # roi_data is samples x features matrix
  # roi_info$id is the region number
  # roi_info$indices are the feature indices
  mean_signal <- mean(roi_data, na.rm = TRUE)
  sd_signal <- sd(roi_data, na.rm = TRUE)
  num_features <- ncol(roi_data)
  list(
    roi_id = roi_info$id, # Can include id if desired, or rely on output table
    mean_signal = mean_signal,
    sd_signal = sd_signal,
    n_features = num_features
  )
}

# Run the custom regional analysis

# Set up parallel processing (optional)

custom_results <- run_custom_regional(dataset_obj, region_mask_vol, my_roi_stats,
                                      .cores = 2, .verbose = TRUE)
print(custom_results)

# Example with an error in one ROI
my_error_func <- function(roi_data, roi_info) {
  if (roi_info$id == 2) {
    stop("Something went wrong in ROI 2!")
  }
  list(mean_signal = mean(roi_data))
}

error_results <- run_custom_regional(dataset_obj, region_mask_vol, my_error_func)
print(error_results)

# Clean up parallel plan
future::plan(future::sequential)

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