Three functions in VertexWiseR do surface data extraction and synthesis: SURFvextract(), FSLRvextract() and HIPvextract().
Surface extraction consists in reading through a preprocessing pipeline’s subjects directory, collating the surface data (for a chosen vertex-wise measures, e.g. thickness), and summarising it into one compact matrix R object, with N rows per subject and M columns per vertex values.
The functions save such objects as a .rds file (which contains the R surface object). This file can be shared across any device with R and all VertexWiseR statistical analyses functions can be run on these, without the need to access the initially preprocessed data.
SURFvextract() extracts cortical surface data from a preprocessed FreeSurfer subjects directory (Fischl 2012).
The function makes use of internal FreeSurfer functions to resample every participant’s individual surface to fsaverage5 or fsaverage6. Therefore, it requires FreeSurfer to be installed and set in the environment where R is run and cannot be automatically run here.
We give the following code as non-executed example:
SPRENG_CTv = SURFvextract(sdirpath = 'path/to/SUBJECTS_DIR',
filename = "SPRENG_CTv.rds",
template='fsaverage5',
measure = 'thickness'
subj_ID = FALSE)
An example of surface matrix object, extracted from FreeSurfer preprocessing of the SPRENG dataset (site 1) (Spreng et al. 2022), is available on VertexWiseR online repository:
SPRENG_CTv = readRDS(file = url("https://github.com/CogBrainHealthLab/VertexWiseR/blob/main/inst/demo_data/SPRENG_CTv_site1.rds?raw=TRUE"))
dim(SPRENG_CTv)
## [1] 238 20484
What dim(SPRENG_CTv) shows is that the matrix object contains the surface values of 238 participants, each with 20484 thickness values which correspond to the vertices of fsaverage5, both left-to-right hemispheres.
When the subj_ID argument is set to TRUE, the object returned is not a matrix on its own but a list containing both the matrix and an array listing the subject IDs from the directory. In our example: * SPRENG_CTv[[1]] will be the list of subject IDs * SPRENG_CTv[[2]] will be the matrix object
FSLRvextract() extracts cortical data in FSLR32k surface space from Human Connectome Project (HCP) (Van Essen et al. 2013) or fMRIprep (Esteban et al. 2019) preprocessing output directories. FSLRvextract() requires the HCP workbench to be installed, and uses the ciftiTools R package to read the .dscalar.nii files.
For demonstration, we provide a subsample of 2 participants from the SPRENG dataset (site 1) (Spreng et al. 2022), after preprocessing their surface data using fMRIprep. The latter outputs fslr32k surface data when using the “–cifti-output” option (Esteban et al. 2019). Other anatomical files were removed and only the dscalar.nii and associated json files were preserved, to minimise its size.
The subsample (14.1 MB) can be downloaded from the repository as follows:
# download and unzip the surface data directory
download.file(url = "https://github.com/CogBrainHealthLab/VertexWiseR/blob/main/inst/demo_data/spreng_surf_data.zip",
destfile = "spreng_surf_data.zip")
untar(zipfile = "spreng_surf_data.zip")
FSLRvextract() gets the data from .dscalar.nii files associated with the specified measure (e.g. thickness, curv), and can extract it as follows:
dat_fslr32k=FSLRvextract(sdirpath="spreng_surf_data/",
wb_path="path/to/workbench",
filename="dat_fslr32k.rds",
dscalar="_space-fsLR_den-91k_thickness.dscalar.nii",
subj_ID = FALSE,
silent=FALSE)
Accordingly, the dat_fslr32k matrix will contain 2 rows (for 2 participants) and 64,984 columns (the subject’s cortical thickness values in every vertex of the fslr32k surface).
HIPvextract() extracts cortical data in CITI168 surface space from the HippUnfold preprocessing pipeline (DeKraker et al. 2023). As opposed to the other two functions, HIPvextract() does not require any system requirement.
For demonstration, we provide a subsample of 2 participants from the Fink dataset (site 1) (Fink et al. 2021), after preprocessing their surface data using HippUnfold, keeping all output .gii files. The subsample (11.3 MB) can be downloaded from the repository as follows:
# download and unzip the surface data directory
download.file(url = "https://github.com/CogBrainHealthLab/VertexWiseR/blob/main/inst/demo_data/fink_surf_data.zip?raw=TRUE",
destfile = "fink_surf_data.zip",
mode = "wb")
untar("fink_surf_data.zip")
To extract and collate the data of the two participants, HIPvextract() can be run as follows:
hipp_surf=HIPvextract(sdirpath="fink_surf_data",
filename="hippocampal_surf.rds",
measure="thickness",
subj_ID = TRUE)
Note that when subjects directories have multiple sessions, the matrix object will contain N rows per participant and per session.
## [1] "sub-season101_ses-1" "sub-season101_ses-2" "sub-season101_ses-3"
## [4] "sub-season102_ses-1" "sub-season102_ses-2" "sub-season102_ses-3"
Here the matrix has 6 rows for 2 particiants with 3 sessions each; and 14,524 columns (the hippocampal thickness values in every vertex of the CITI168 surface).
## [1] 6 14524