# Surface-based analysis of MRI data using Freesurfer and Connectome workbench ---------------------------------------------------------- @[toc] ## Required software The following instruction will assume that the following software / data is downloaded and installed on your machine. - [Freesurfer][1] - [Connectome Workbench][2] - [Our version of atlases][3] - [SurfAnalysis Toolbox for Matlab][4] OR - [SurfAnalysis Toolbox for Python][18] Ensure that all software is properly installed and up-to-date. Your batch script should be set properly, such that freesurfer and workbench command line tools are in your Path. The SurfAnalysis toolbox for Matlab or Python should be installed. Note that we are usually first developing new features in Matlab and then translating to Python, so you may find more functionality in the Matlab version. ## Standard Surface Spaces One of the emerging standards in terms of a cortical surface-based group standard spaces are the fs_LR_32 and fs_LR_164. Both are spaces defined on a standard sphere. Different from the old fsaverage group surface, the fs_LR space is symmetric across the left and right hemisphere. That is, a vertex with a specific number will refer to roughly homologous areas in each hemisphere. The fs_LR surface comes in 2 resolutions, either with ~32k or ~164k vertices. For standard functional imaging analysis with a voxel size of >1.4mm, the 32k surface has high enough resolution to give at least one vertex per gray matter voxel. The fs_LR surface comes with the tutorial data set of the Connectome Workbench. To make life easier, we provide a Git-Hub repository that contains the essential files and a number of useful group atlases for download. ## Atlases ### Glasser 2016 The Human Connectome Project's Multi-modal Cortical Parcellation (HCP_MMP1.0) delineates 180 areas per hemisphere bounded by sharp changes in cortical architecture, function, connectivity, and/or topography. The parcellations were created using multimodal MRI data from 210 healthy young adults collected as part of the HCP. More details can be found on Washington University's BALSA website [here][6]; full description can be found in the [Glasser et al. 2016 Nature paper][7]. @[osf](ycebg) ### Yeo 2011 Resting state data from 1000 healthy, young adults were input into a clustering approach to identify and replicate functionally connected networks of brain regions. The clustering approach resulted in two parcellations: a seven network parcellation (upper panel shown below) and a seventeen network parcellation (lower panel shown below). The seven network parcellation includes visual, somatomotor, dorsal attention, ventral attention, limbic, frontoparietal, and default networks. The seventeen network parcellation does not ascribe functional labels to the individual parcels. More details can be found on the Freesurfer website [here][8]; a full description can be found in the [Yeo et al., 2011 J Neurophysiology paper][9]. @[osf](fc9ae) @[osf](8dk4a) ### Icosahedron Sometimes it is useful to subdivide the cortical surface into regions of interest of equal sizes, irrespective of anatomical details. We provide here different regular tesselations of the two hemispheres, in form of a icosahedron, a 3D regular polyhedron with equilateral triangles as faces. Here, icosahedron tesselation was performed on the fs_LR spherical templates, separately for the left and right hemisphere. Instead of choosing a triangular shape of tessels, the fs_LR vertices were assigned to the closest triangular vertex, resulting in a **hexagonal tesselation**, similar to the geometry observed in a soccer ball (see figure below). Freesurfer definition of medial wall was used to exclude any tessels residing within the medial wall. Here we have provided **different resolutions of tesselation** with **42, 162, 362, 642, 1002, **and** 1442 tessels per hemisphere**. They are named accordingly (e.g. Icosahedron-42 vs. Icosahedron-162). **NB:** The number of tessels in the name is related to the total number of tessels obtained from the icosahedron before medial wall removal. Therefore in practice it is best to check the number of unique tessels per hemisphere before defining regions or extracting data from each tessel. *Left:* left hemisphere with 1002 tessels\ *Right:* right hemisphere with 362 tessels @[osf](pr8xh) ### Brodmann area probabilistic atlas The Brodmann area (BA) probabilistic atlas is created using a probabilistic cytoarchitectonic map ([Fischel et al., *Cerebral Cortex*, 2008][10]). This atlas was constructed using whole-brain histology of 10 postmortem human brains. The BAs included in the atlas are: BA 1, 2, 3a, 3b, 4a, 4p, 44, 45, 17, 18, and the Middle Temporal visual area of BA 19. Each surface node in this atlas is assigned a probability of belonging to each BA included in the atlas. This atlas can be used to define regions of anatomical interest using cellular structure, for example, by labeling nodes with a maximal probability of being one of the BAs. We have resampled this atlas into both the 32k and the 164k surfaces (one file per hemisphere). As an example, the left hemisphere atlas for the 164k surface is named *BAprobatlas.164k.L.func.gii*. @[osf](k95ce) *Top row:* lateral views of the left and right hemispheres.\ *Bottom row:* medial views of the left and right hemispheres.\ This gif cycles through each BA included in this atlas file. Brighter colours (e.g. yellow) indicate a higher probability of belonging to each BA. ### Power 2011 This thirteen network parcellation was defined using graph theory on resting-state fMRI data, using both parcel- (AAL atlas) and voxel-based methods. The parcellations include the default mode, dorsal attention, ventral attention, fronto-parietal task control, visual, auditory, hand, face, two cingulo-opercular networks, along with three subgraphs with no functional labels. Details on the atlas formation are described in the [Power et al., 2011 Neuron paper][11]. @[osf](x3gka) ### Yeo 2015 Hierarchical Bayesian modelling was applied to 10,449 Brainmap experiments across 83 different behavioral tasks. The model revealed a nest ontology, from which quantitative maps of functional specialization were derived. The twelve component model is shown below, as this is the model most useful for fMRI studies. The parcels themselves have no definite functional labels, rather the authors provide the probability of the component mapping to one or more of the 83 behavioral tasks identified from the Brainmap database. More information can be found [here][12] on the Freesurfer website; full details on all the analyses can be found in the [Yeo et al., 2015 Cerebral Cortex paper][13]. @[osf](pqjxv) ## Overview of workflow ### Step 1: Individual surface reconstruction Individual surface reconstruction is performed by freesurfer software, using recon-all. What is needed is a 3D T1-weighted image (ideally 1mm resolution or better) of the subject's anatomy. ``` recon-all -s <subj_name> -i <T1image.nii> -all -cw256 ``` This process take several hours (or more) per subject, and produces freesurfer files in the directory <SUBJECT_DIR>/<subj_name>. As part of the process, freesurfer also does a spherical alignment of each individual hemisphere to the fsaverage template. **N.B.:** The BIDS app, fMRIPrep, automatically runs Freesurfer's ``` recon-all ``` as part of its standard workflow, unless the Freesurfer option is explicitly turned off. ### Step 2: Resampling individual surfaces into fs_LR space The next step is to resample the individual surface from fsaverage space (e.g., the Freesurfer output created in Step 1) into fs_LR space. You can do this by calling the Matlab toolbox function: ``` surf_resliceFS2WB(subj_name,fsDir,wbDir,'resolution','32k') ``` As inputs, the function requires the location of the Freesurfer ```<SUBJECTS_DIR>``` (```fsDir```), the location of the directory to which the resampled, Workbench format files will be written (```wbDir```), and the subject ID (```subj_name```). The function will create a subfolder for the subject in wbDir and save all gifti files there. By default, the function resamples the white, pial, and inflated surface. It also creates files for the sulcal depth, curvature, and area. Unless ```resolution``` is specified in the function call, the default resampling will be to the ~32k surface. **N.B.:** For additional information on the default Freesurfer directory setup and how to change the location of Freesurfer's ```<SUBJECTS_DIR>```, please see following the Freesurfer wiki [page][14]. ### Step 3: Mapping data from volume to surface After the subject's anatomical images have been resampled into fs_LR space, the next step is to map any volumetric functional files (e.g., statistical parametric maps) to surface space via the individual surface. You can do this by calling the Matlab toolbox function: ``` surf_vol2surf(c1,c2,V,'anatomicalStruct','CortexLeft') ``` As inputs, the function requires a Px3 matrix of vertices (x,y,z coordinates) for the individual's white surface (```c1```), a Px3 matrix of vertices (x,y,z coordinates) for the individual's pial surface (```c2```), and a list of volumes (loadable with spm_vol) to be mapped (```V```). These files were generate in step 2. Unless ```anatomicalStruct``` is specified in the function call, the default surface is ```CortexLeft```; other options are ```Cerebellum``` and ```CortexRight```. ### Step 4: Summarizing individual data in group files Finally, to make a group gifti file containing the surface data from multiple subjects, the following Matlab toolbox function can be called: ``` surf_groupGiftis(P,'groupsummary','groupSummaryFile') ``` As input, the function takes a cell array of N ```func.gii``` files (one file per subject) with P experimental conditions, such as those created during Step 3. If no cell array is specified, the function will prompt the user to select the ```func.gii``` files using ```spm_select()```. The function creates P group ```func.gii``` files (one group file per experimental condition) with N columns (one column per each subject). If ```groupsummary``` is specified in the function call, the function will also produce a single group summary file of the mean across all subjects, with one column for each experimental condition. ## Quick guide to surface file types (adapted from [here][15]) ### GIFTI format (*.gii) GIFTI is the main data file format for surface-based data. For further details see the following page on [NITRC][16]. #### Surface geometry files (*.surf.gii) Surface geometry files specify 3D vertex coordinates and their topological relationships (e.g., faces). #### Metric files (*.func.gii, *.shape.gii) Metric files encode continuous values for each vertex. By convention, fMRI data are saved as *.func.gii and cortical folding data as *.shape.gii. Otherwise, these two file formats are identical. #### Label files (*.label.gii) Label files encode integer values for each vertex. Label files also contain a table of a name and color for each value, referred to as a 'label table'. ### CIFTI format (*.nii) CIFTI files are designed to handle data contained in multiple non-contiguous anatomical structures (e.g., surface data from both hemispheres AND volumetric data from subcortical structures). Structures can be excluded (e.g., white matter, CSF, 'medial wall') to make the file more compact. Vertices and voxels encoded in a CIFTI file are referred to as 'brainordinates', or in the case of gray matter locations, 'grayordinates'. Please see the following page in [NITRC][17] for more information. #### CIFTI 'mapping types' CIFTI files contain a single rectangular data matrix. Each dimension is described using one of five CIFTI 'mapping types' (two spatial and three non-spatial). ##### Dense or 'brain models' Dense is a spatial mapping type that represents both hemispheres and all subcortical structures concurrently, both surface- and voxel-based. ##### Parcels Parcels is a spatial mapping type that groups related brainordinates into areas, resulting in smaller data files, as values are stored per parcel rather than per voxel/vertex. ##### Scalars Scalars is a non-spatial mapping type that gives each index a name (e.g., 'Myelin'). ##### Series Series is a non-spatial mapping type that assigns each index a quantity in a linear series (e.g., frequency in Hz, timeseries in sec). ##### Labels Labels is a non-spatial mapping type that assigns each index a name (e.g., 'Visual Areas'). This mapping type also includes a label table that maps the data values to names and colors, similar to *.label.gii files. The labels mapping type assumes that the data values are integers. #### CIFTI file types ##### .dconn A 'dense' by 'dense' matrix (e.g., 'dense connectome' from resting-state fMRI) ##### .dscalar One or more dense maps of scalar values (e.g., myelin or curvature maps) ##### .dtseries One or more dense timeseries datasets or other data at equal intervals (e.g., fMRI timeseries) ##### .dlabel One or more dense maps of integer values, plus a label table that defines each integer ##### .dpconn A parcel by dense matrix ##### .pconn A parcel by parcel matrix (e.g., parcellated connectome) ##### .pscalar One or more parcellated scalar maps ##### .ptseries A parcellated timeseries ##### .plabel One or more parcel maps, with corresponding label table(s) ##### .sdseries Rows of series data (frequency, time, etc.). This data type is *not* mapped to brainordinates and is viewed as a matrix or line chart. ##### .fiberTemp Orientations of dMRI fibers. This file format is the same as 'dscalar', but the arrangement of maps within the file type is fixed so that Workbench correctly interprets the file as containing fiber orientations. [1]: https://surfer.nmr.mgh.harvard.edu/fswiki/DownloadAndInstall [2]: https://www.humanconnectome.org/software/connectome-workbench [3]: https://www.diedrichsenlab.org/download/xxx.zip [4]: https://github.com/jdiedrichsen/surfAnalysis [18]: https://github.com/DiedrichsenLab/surfAnalysisPy [5]: https://doi.org/10.1038/nature18933 [6]: https://balsa.wustl.edu/study/show/RVVG [7]: https://doi.org/10.1038/nature18933 [8]: https://surfer.nmr.mgh.harvard.edu/fswiki/CorticalParcellation_Yeo2011 [9]: https://www.ncbi.nlm.nih.gov/pubmed/21653723 [10]: https://academic.oup.com/cercor/article/18/8/1973/287246 [11]: https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3222858/ [12]: https://surfer.nmr.mgh.harvard.edu/fswiki/BrainmapOntology_Yeo2015 [13]: http://people.csail.mit.edu/ythomas/publications/2015BrainMapAssociation-CerebCor.pdf [14]: https://surfer.nmr.mgh.harvard.edu/fswiki/DownloadAndInstall [15]: https://balsa.wustl.edu/about/fileTypes [16]: http://www.nitrc.org/projects/gifti/ [17]: http://www.nitrc.org/projects/cifti/