Structural processing
Table of Contents
This section describes all structural processing modules, which include pre-processing and post-processing of T1-weighted images found in the BIDS directory. Structural processing modules perform volumetric (-proc_structural
) and surface-based (-proc_surf
, -post_structural
, -GD
) processing. These modules map subject data to volumetric and surface templates providing several useful structural metrics for further analyses, including geodesic distance matrices mapped to multiple parcellation schemes as well as vertexwise cortical thickness and curvature data.
-proc_structural
This module performs initial structural pre-processing, keeping data in volumetric format. Two main spaces are found in this stream: nativepro as well as MNI152.
Nativepro?! 🤨
Nativepro stands for native processing space. This denomination is used to distinguish the space occupied by the main scan from standard native space. Indeed, as micapipe supports the alignment and averaging of several distinct T1w acquisitions, we opted to refer to the resulting space using a different term, so not to confuse this space with the native space of each original T1w scan.
Each T1-weighted run is LPI-reoriented, deobliqued, and oriented to standard space (MNI152).
If an MP2RAGE uni image is used an algorithm to denoise the salt and pepper backgroun noise is applied here
Create the T1-weighted image used in all downstream processing:
T1_nativepro
. If multiple T1w scans are found in the raw data, they are aligned to the first run and averaged.Intensity non-uniformity correction (N4)
Intensity rescaling [100,0]
Create brain mask (mri_synthstrip)
Subcortical structure segmentation using FSL FIRST
Tissue type segmentation (Gray matter, white matter, CSF) using FSL FAST
White matter weighted intensity normalization
Non-linear registration to MNI152 (0.8mm and 2mm resolutions)
Five-tissue-type image segmentation (5ttgen, used for anatomically constrained tractography)
Terminal:
$ micapipe -sub <subject_id> -out <outputDirectory> -bids <BIDS-directory> -proc_structural <options>
Optional arguments
-proc_structural
only has one optional argument, which specifies the string name(s) of the T1w image(s) you want to process.
Optional argument |
Description |
---|---|
|
This option allows manual selection of the main scan(s) for structural processing. It should be separated by a comma, with no blank spaces: eg. |
|
Special workflow to use the UNI-T1map image as the structural reference (eg. 7T UNI-T1map). Default = no processing of UNI-T1maps. |
|
Multiplying factor for the mp2rage denoising. Greater value removes more noise (eg. UNI-T1map use with -uni). Default = 3 (7T), recomended value of 45 for 3T MP2RAGE. |
In the following example, if multiple T1w are found inside the BIDS/<sub>/anat directory, only the MRI volume containing the string run-02_T1w
will be processed:
1 micapipe -sub <subject_id> -out <outputDirectory> -bids <BIDS-directory> \
2 -proc_structural -T1wStr run-02_T1w
Directories created or populated by -proc_structural will be under each SubjectDir
which is <outputDirectory>/micapipe/<sub>
.
- <SubjectDir>/anat
- <SubjectDir>/xfm
Files generated by -proc_structural:
- Main structural scan: - <SubjectDir>/anat/<sub>_space-nativepro_T1w.nii.gz - Brain extracted main structural scan: - <SubjectDir>/anat/<sub>_space-nativepro_T1w_brain.nii.gz - Brain-mask for main structural scan: - <SubjectDir>/anat/<sub>_space-nativepro_T1w_brain_mask.nii.gz - FSL FAST outputs stored in <SubjectDir>/anat/: - <sub>_space-nativepro_T1w_brain_pve_0.nii.gz - <sub>_space-nativepro_T1w_brain_pve_1.nii.gz - <sub>_space-nativepro_T1w_brain_pve_2.nii.gz - Main structural scan non-linear transformations to MNI152 0.8mm: <SubjectDir>/xfm/ - <sub>_from-nativepro_brain_to-MNI152_0.8mm_mode-image_desc-SyN_0GenericAffine.mat - <sub>_from-nativepro_brain_to-MNI152_0.8mm_mode-image_desc-SyN_1InverseWarp.nii.gz - <sub>_from-nativepro_brain_to-MNI152_0.8mm_mode-image_desc-SyN_1Warp.nii.gz - <sub>_from-nativepro_brain_to-MNI152_0.8mm_mode-image_desc-SyN_InverseWarped.nii.gz - Main structural scan non-linear transformations to MNI152 2mm: <SubjectDir>/xfm/ - <sub>_from-nativepro_brain_to-MNI152_2mm_mode-image_desc-SyN_0GenericAffine.mat - <sub>_from-nativepro_brain_to-MNI152_2mm_mode-image_desc-SyN_1InverseWarp.nii.gz - <sub>_from-nativepro_brain_to-MNI152_2mm_mode-image_desc-SyN_1Warp.nii.gz - <sub>_from-nativepro_brain_to-MNI152_2mm_mode-image_desc-SyN_InverseWarped.nii.gz - Final 5ttgen output: - <SubjectDir>/anat/<sub>_space-nativepro_T1w_5TT.nii.gz - Json cards are in <SubjectDir>/anat/: - <sub>_space-nativepro_T1w_brain_mask.json - <sub>_space-nativepro_T1w.json
-proc_surf
This modules performs cortical surface segmentation from all native T1w acquisitions stored in the subject’s BIDS directory.
Quality control 💅🏻
We recommend that users carefully inspect FastSurfer/FreeSurfer-generated cortical surface segmentations. As micapipe relies heavily on surface-based processing, poor segmentation quality may compromise the validity of downstream results. FreeSurfer provides comprehensive tutorials for manual correction of surface segmentations: See tutorials ‘Control Points’, ‘White matter’, and ‘Pial edits’ explaining different types of corrections that can be applied to cortical surfaces.
FastSurfer has this entry on manual edits for the mask: https://github.com/engrosamaali91/FastSurfer/blob/m-reuter-editing-1/EDITING.md
Run surface reconstruction (fastsurfer or freesurfer) pipeline will all T1-weighted scans found in raw data directory
Terminal:
$ micapipe -sub <subject_id> -out <outputDirectory> -bids <BIDS-directory> -proc_surf <options>
Optional arguments
-proc_surf
has a few optional arguments, including an option for T1w scan selection as in proc_volumetric
.
Optional argument |
Description |
---|---|
|
Same option as in |
|
Use this option to reconstruct the cortical surface with Freesurfer 7. Default surface reconstruction uses ‘FastSurfer’ |
|
This option will copy existing FreeSurfer outputs in the provided path to the appropriate location. This way, if the cortical segmentations of your dataset have already been quality controlled, results can be easily integrated within the pipeline’s directory structure. |
|
Provide the full path to the freesurface licence. e.g. /home/documents/licence.txt’. If you don’t have a licence you can get one here: https://surfer.nmr.mgh.harvard.edu/registration.html |
|
Overwrite the t1 input, MUST be ‘nii.gz’. Use the full path to a T1w image to be processed. By default micapipe uses t1nativepro to generate the surfaces. |
Directories created or populated by -proc_surf:
- <outputDirectory>/freesurfer/<sub>
- <outputDirectory>/fastsurfer/<sub>
Files generated by -proc_surf:
- A list of all recon-all output files can be found here: ReconAllOutputFiles.
-post_structural
This first structural post-processing module registers native FreeSurfer-space cortical surfaces to a standard template, in addition to mapping all cortical parcellation schemes to the subject’s native surface space and volumetric nativepro space.
Prerequisites 🖐🏼
You need to run -proc_structural
and -proc_surf
before this stage.
Compute affine registration from native Surfer space to nativepro space
Register cerebellar atlas (MNI152) to subject’s nativepro space using affine transformation
Perform surface-based registration of fsaverage5 annotation labels to native surface
Register native surface parcellations to native Surfer volume
Apply linear registrations to bring volumetric parcellations to nativepro space
Apply linear registrations to bring surfaces to nativepro space
Register thickness and curvature to nativepro space
Build fsLR-32k sphere and resample white and pial surfaces to fsLR-32k and fsLR-5k template
Create midthickness surface from native surface and resampled fsLR-32k and fsLR-5k template
Terminal:
$ micapipe -sub <subject_id> -out <outputDirectory> -bids <BIDS-directory> -post_structural <options>
Optional arguments:
-post_structural
only has one optional argument:
Optional argument |
Description |
---|---|
|
Registers only selected parcellations to subject space (e.g. economo,aparc). By default, all 18 parcellations included in the pipeline will be registered to the subject’s native volumetric and surface space. Below is the list of all the possible options: |
The following parcellations are available in micapipe:
|
|
|
The next example will only process the three selected parcellations (schaefer-200,economo,aparc
)
1 micapipe -sub <subject_id> -out <outputDirectory> -bids <BIDS-directory> \
2 -post_structural -atlas schaefer-200,economo,aparc
Thinking ahead ☂️
Functional and structural connectomes, microstructural profile covariance, and geodesic distance matrices will be calculated only on the parcellations selected in this step. If another parcellation should be added after this module, -post_structural
and its dependent modules have to be re-run.
Directories created or populated by -post_structural
will be under each SubjectDir
which is <outputDirectory>/micapipe/<sub>
and freesurferDir
which is <outputDirectory>/freesurfer/<sub>
:
- <SubjectDir>/anat
- <SubjectDir>/surf
- <SubjectDir>/maps
- <SubjectDir>/parc
- <SubjectDir>/xfm
Files generated by -post_structural
:
- Main structural scan (nativepro) in FreeSurfer space: - <SubjectDir>/anat/<sub>_space-fsnative_T1w.nii.gz - Surface files resampled to fsaverage5, fsLR-32k and fsLR-5k templates, stored in <SubjectDir>/surf: - Pial - <sub>_hemi-L_space-nativepro_surf-<template>_label-pial.surf.gii - White matter - <sub>_hemi-L_space-nativepro_surf-<template>_label-white.surf.gii - Midsurface - <sub>_hemi-L_space-nativepro_surf-<template>_label-midthickness.surf.gii - Sphere - <sub>_hemi-L_surf-fsnative_label-sphere.surf.gii - Maps mapped to surface template, stored in <SubjectDir>/surf L-left and R-right: - <SubjectDir>_hemi-L_surf-fsaverage5_label-thickness.func.gii - <SubjectDir>_hemi-L_surf-fsLR-32k_label-thickness.func.gii - <SubjectDir>_hemi-L_surf-fsLR-5k_label-thickness.func.gii - <SubjectDir>_hemi-L_surf-fsnative_label-thickness.func.gii - Native surface mapped annotation labels: - <freesurferDir>/parc/<hemi>.<parcellation>_mics.annot - Native midsurface: - <freesurferDir>/surf/<hemi>.midthickness.surf.gii - Volumetric parcellation files: - <c>/parc/<sub>_space-nativepro_T1w_atlas-<parcellation>.nii.gz - Files generated for affine registration between native FreeSurfer space and nativepro: - <SubjectDir>/xfms/<sub>_from-fsnative_to_nativepro_T1w_0GenericAffine.mat
<parcellation>
stands for the name of each of the 18 parcellations. <hemi>
is either lh
or rh
.
Surfaces generated by this module:
-GD
This module calculates geodesic distance between all cortical parcels from the subject’s native midsurface mesh using Dijkstra’s algorithm.
Prerequisites 🖐🏼
You need to run -proc_structural
, -proc_surf
and -post_structural
before this stage
Identify centre vertex for each parcel, based on the vertex with the shortest summed Euclidean distance to all other vertices in the same parcel
Calculate geodesic distance from centre vertex to all other vertices on the midsurface mesh using workbench -surface-geodesic-distance
Average computed distances within parcels
Terminal:
$ micapipe -sub <subject_id> -out <outputDirectory> -bids <BIDS-directory> -GD
No optional arguments
Directories created or populated by -GD:
- <SubjectDir>/dist/
One file per parcellation is generated by -GD:
- Square matrix of average parcel-to-parcel geodesic distances: - <sub>_atlas-<parcellation>_GD.shape.gii
<parcellation>
stands for the name of each of the 18 parcellations.