This is an old revision of the document!

Surface-based Analysis (cifti)

Surface files track vertices instead of volumetric voxels. Files are created by tools like xcpd.

Types

citfi files have double extentions like *.dscalar.nii. See https://balsa.wustl.edu/about/fileTypes for more. From there, highlights are:

dscalar one or more dense maps of scalar values (e.g., myelin maps, curvature maps)
dtseries one or more dense timeseries datasets (e.g., fMRI timeseries) or other data at equal intervals
dlabel one or more dense maps of integer values, plus a ‘label table’ that defines each integer (e.g., one or more parcellations of cerebral cortex, subcortical nuclei, or all grayordinates)
pscalar one or more parcellated scalar maps (e.g., a parcellated thickness map having uniform thickness within each parcel
ptseries parcellated timeseries
plabel one or more parcel maps, where each parcel is identified and colored using a label

Working with surface data in R

See Val's tutorial on github https://github.com/PennLINC/surfaces_R_tutorial/blob/main/surface_tools_R.Rmd which covers information about cifti files and the fslr surface, types of ciftis/giftis, and how to read, manipulate, write, and visualize dense and parcellated cortical surface data in R

Working with surface data using Connectome Workbench

Download connectome workbench using these commands in your terminal
(for ubuntu https://neuro.debian.net/pkgs/connectome-workbench.html; otherwise https://www.humanconnectome.org/software/get-connectome-workbench) 

# check your release Codename matches (2025-05-27: ubuntu 24.04 = 'noble')
lsb_release -a

# add repo to get neurodebian packages
wget -O- http://neuro.debian.net/lists/noble.us-nh.full | sudo tee /etc/apt/sources.list.d/neurodebian.sources.list
sudo apt-key adv --recv-keys --keyserver hkps://keyserver.ubuntu.com 0xA5D32F012649A5A9

# install connectome workbench
sudo apt-get update
sudo apt-get install connectome-workbench

Now you should be able to open files in connectome-workbench with wb_view [file path/file name]

Connectome Workbench Tools

See all of the available workbench commands here https://www.humanconnectome.org/software/workbench-command/-cifti-create-dense-timeseries

wb_command examples: 

wb_command -volume-to-surface-mapping /Volumes/Hera/Projects/mMR_PETDA/group_analysis_ashley/ANTI-SACCADE/Anti_harOx_1mm_gmmask.nii.gz /Volumes/Hera/Projects/Habit/mr/tpl/tpl-fsLR_den-32k_hemi-L_midthickness.surf.gii /Volumes/Hera/Projects/Habit/mr/tpl/anti_ashley_atlas.surf.func.gii -trilinear
wb_command -cifti-parcellate /Volumes/Hera/Projects/Habit/mr/xcpd/prep-25.0.0_type-cifti_fd-0.3_bp-yes/sub-11734/ses-1/func/sub-11734_ses-1_task-rest_run-1_space-fsLR_den-91k_stat-reho_boldmap.dscalar.nii /Volumes/Hera/Projects/mMR_PETDA/group_analysis_ashley/ANTI-SACCADE/Anti_harOx_1mm_gmmask.dlabel.nii COLUMN /Volumes/Hera/Projects/Habit/mr/xcpd/prep-25.0.0_type-cifti_fd-0.3_bp-yes/sub-11734/ses-1/func/sub-11734_ses-1_task-rest_run-1_space-fsLR_den-91k_seg-antisaccadeatlas_stat-reho_boldmap.pscalar.nii

https://github.com/LabNeuroCogDevel/corticalmyelin_maturation/blob/e95717f6de71103cc24df2ecb6ed315f8acb99a7/results/R1_corticalmyelin_anatomy/myelin_maps/parcellate_MWFmap.sh#L9

wb_view

Connectome wb_view is a GUI for visualization surface data, which can be downloaded here https://www.humanconnectome.org/software/get-connectome-workbench.

To visualize surface data in workbench, you must load a .surf.gii surface geometry first, and then your surface data. On Rhea (linux server), TemplateFlow has already downloaded some of these to /opt/ni_tools/templateflow/tpl-fsLR.

To see your files on a surface: File > Load /Volumes/Hera/Projects/Habit/mr/tpl/tpl-fsLR_den-32k_hemi-L_midthickness.surf.gii

wb_view example: 

 wb_view /Volumes/Hera/Projects/Habit/mr/tpl/tpl-fsLR_den-32k_hemi-L_midthickness.surf.gii /Volumes/Hera/Projects/Habit/mr/xcpd/prep-25.0.0_type-cifti_fd-0.3_bp-yes/sub-11734/ses-1/func/sub-11734_ses-1_task-rest_run-1_space-fsLR_den-91k_stat-reho_boldmap.dscalar.nii /Volumes/Hera/Projects/mMR_PETDA/group_analysis_ashley/ANTI-SACCADE/Anti_harOx_1mm_gmmask.dlabel.nii /Volumes/Hera/Projects/Habit/mr/xcpd/prep-25.0.0_type-cifti_fd-0.3_bp-yes/sub-11734/ses-1/func/sub-11734_ses-1_task-rest_run-1_space-fsLR_den-91k_seg-antisaccadeatlas_stat-reho_boldmap.pscalar.nii