SURFvextract

Extracts whole-brain vertex-wise surface-based measures for each subject in a 'FreeSurfer' output subjects directory, resamples the data to a common surface template, and stores it as a .rds file. This function requires the 'FreeSurfer' environment to be preset and a 'FreeSurfer' license key.

Usage

SURFvextract(
  sdirpath = "./",
  filename,
  template = "fsaverage5",
  measure = "thickness",
  subj_ID = TRUE
)

Arguments

sdirpath

A string object containing the path to the 'FreeSurfer' subjects directory. Default is the current working directory ("./").

filename

A string object containing the desired name of the output RDS file. Default is 'brain_measure.rds' in the R temporary directory (tempdir()).

template

A string object containing the name of surface template (available: 'fsaverage5', 'fsaverage6'). Default is fsaverage5.

measure

A string object containing the name of the measure of interest. Options are thickness, curv, sulc, area, and volume (for freesurfer 7.4.1 or later). Default is thickness.

subj_ID

A logical object stating whether to include subject IDs (folder names in the subjects directory) as a first column to the output matrix. Default is TRUE.

Value

A .RDSfile with a list containing 1. the list of subject IDs (first element) and 2. a surface data matrix object (second element), or only a data matrix object. The matrix has N subjects x M vertices dimensions and can be used readily by VertexWiseR statistical analysis functions. Each row corresponds to a subject (in the order they are listed in the folder) and contains the left to right hemispheres' vertex-wise values.

Details

The function runs system shell commands that will produce in the set subjects directory: 1) a sorted list of subjects "sublist.txt"; 2) a link file to the selected surface fsaverage template. 3) left and right hemisphere .mgh maps outputted by 'FreeSurfer' 's mris_preproc.

Examples

SURFvextract(sdirpath = "freesurfer_subjdir", 
filename=paste0(tempdir(), "/CTv.rds"), template="fsaverage5",
measure="curv") 
#> No FREESURFER_HOME variable has been set. SURFvextract() will not be able to work without FreeSurfer.