Process ROI Voxel Data from a NIfTI File

Processes Regions of Interest (ROIs) from a binary NIfTI file by extracting voxel-level coordinates and labeling each voxel as part of the ROI or not. The function preserves the spatial structure and is typically used to prepare ground truth ROIs for comparison with SCC-detected regions via calculateMetrics.

Usage

processROIs(
  roiFile,
  region,
  number,
  save = TRUE,
  outputDir = tempdir(),
  verbose = TRUE
)

Arguments

roiFile

character. Path to the binary NIfTI file containing ROI data.

region

character. Name of the ROI region (e.g., "Region2").

number

character. Identifier for the subject or group (e.g., "18").

save

logical. If TRUE, saves the result as an .RDS file. If FALSE, returns a data frame in the console. Default is TRUE.

outputDir

character. Directory where the ROI table will be saved if save = TRUE. Default is a temporary file: tempdir().

verbose

logical. If TRUE, displays progress messages. Default is TRUE.

Value

A data frame with voxel-level ROI information.

• group – Combined identifier built from region and number.

• z, x, y – Voxel coordinates.

• pet – Binary value indicating ROI membership (1 = ROI, 0 = non-ROI).

If save = TRUE, the data frame is saved as an .RDS file and not returned to the console.

Details

The function uses neuroCleaner to load and flatten the NIfTI file into a structured data frame. All voxels are retained, with the pet column indicating which ones are part of the ROI (1) versus background (0). An ROI label is added in the group column.

This output is used as ground truth for evaluating detection performance in SCC analyses.

See also

calculateMetrics for evaluating SCC detection performance.
neuroCleaner for reading and structuring voxel data.

Examples

# Load and process a sample ROI NIfTI file (console output)