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-freesurfer, -post_structural, -GD, -Morphology) 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).
- 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 (FSL-BET)
- Subcortical structure segmentation using FSL FIRST
- Tissue type segmentation (Gray matter, white matter, CSF) using FSL FAST
- Non-linear registration to MNI152 (0.8mm and 2mm resolutions)
- Five-tissue-type image segmentation (5ttgen, used for anatomically constrained tractography)
Terminal:
$ mica-pipe -sub <subject_id> -out <outputDirectory> -bids <BIDS-directory> -proc_structural <options>
Docker command:
$ docker -proc_structural
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 |
|---|---|
-t1wStr <str> |
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. -t1wStr run-02_T1w. By default the pipeline uses the string T1w.nii. This option can be useful if the user wishes to exclude one or several T1w scans from further processing. |
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 2 | mica-pipe -sub <subject_id> -out <outputDirectory> -bids <BIDS-directory> \
-proc_structural -t1wStr run-02_T1w
|
Multiple T1-weighted images 🧠 🧠 🧠
Be sure you use the same T1w images in -proc_structural and -proc_freesurfer. Although they are independent modules, when using the same image the registrations will be much better.
Directories created or populated by -proc_structural will be under each SubjectDir which is <outputDirectory>/micapipe/<sub>.
- <SubjectDir>/anat
- <SubjectDir>/anat/first
- <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_seg.nii.gz
- <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
- <sub>_space-nativepro_t1w_brain_pveseg.nii.gz
- <sub>_space-nativepro_t1w_brain_mixeltype.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
- <sub>_from-nativepro_brain_to-MNI152_0.8mm_mode-image_desc-SyN_Warped.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
- <sub>_from-nativepro_brain_to-MNI152_2mm_mode-image_desc-SyN_Warped.nii.gz
- Final 5ttgen output:
- <SubjectDir>/anat/<sub>_space-nativepro_t1w_5TT.nii.gz
- FSL FIRST intermediary files:
- <SubjectDir>/anat/first/
- If multiple T1w scans are found in the raw data directory, transformation files to generate nativepro image will be generated:
- <SubjectDir>/xfm/<sub>_t1w_from-run-2_to_run-1_0GenericAffine.mat
- <SubjectDir>/xfm/<sub>_t1w_from-run-2_to_run-1_InverseWarped.nii.gz
- <SubjectDir>/xfm/<sub>_t1w_from-run-2_to_run-1_Warped.nii.gz
- Json cards are in <SubjectDir>/anat/:
- <sub>_space-nativepro_t1w_brain_mask.json
- <sub>_space-nativepro_t1w.json
-proc_freesurfer¶
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 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.
- Run FreeSurfer’s recon-all pipeline will all T1-weighted scans found in raw data directory
Terminal:
$ mica-pipe -sub <subject_id> -out <outputDirectory> -bids <BIDS-directory> -proc_freesurfer <options>
Docker command:
$ docker -proc_freesurfer -<options>
Optional arguments
-proc_freesurfer has a few optional arguments, including an option for T1w scan selection as in proc_volumetric.
| Optional argument | Description |
|---|---|
-t1wStr <str> |
Same option as in -proc_structural, this will allow to manually select the main scan(s) for structural processing. |
-freesurfer_dir <path> |
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. |
-hires |
Use this option for data with voxel sizes less than 1mm3 at native resolution (e.g. isometric 7T acquisitions. Requires -proc_structural). For further information see SubmillimeterRecon. |
Directories created or populated by -proc-freesurfer:
- <outputDirectory>/freesurfer/<sub>
Files generated by -proc-freesurfer:
- 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_freesurfer before this stage.
- Compute affine registration from native FreeSurfer 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 FreeSurfer volume
- Apply linear registrations to bring volumetric parcellations to nativepro space
- Build conte69-32k sphere and resample white and pial surfaces to conte69-32k template
- Create midthickness surface from native surface and resampled conte69-32k template
Terminal:
$ mica-pipe -sub <subject_id> -out <outputDirectory> -bids <BIDS-directory> -post_structural <options>
Docker command:
$ docker -post_structural
Optional arguments:
-post_structural only has one optional argument:
| Optional argument | Description |
|---|---|
-atlas <str> |
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 2 | mica-pipe -sub <subject_id> -out <outputDirectory> -bids <BIDS-directory> \
-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>/anat/surfaces/conte69
- <SubjectDir>/anat/surfaces/label
- <SubjectDir>/anat/volumetric
- <SubjectDir>/xfm
- <freesurferDir>/surf
- <freesurferDir>/label
Files generated by -post_structural:
- Main structural scan (nativepro) in FreeSurfer space:
- <SubjectDir>/anat/<sub>_space-fsnative_t1w.nii.gz
- Surface files resampled to Conte69 32k-vertex template, stored in <SubjectDir>/anat/surfaces/conte69:
- Pial
- <sub>_space-conte69-32k_desc-<hemi>_pial.surf.gii
- White matter
- <sub>_space-conte69-32k_desc-<hemi>_white.surf.gii
- Midsurface
- <sub>_space-conte69-32k_desc-<hemi>_midthickness.surf.gii
- Sphere
- <sub>_<hemi>_sphereReg.surf.gii
- Native surface mapped annotation labels:
- <freesurferDir>/labels/<hemi>.<parcellation>_mics.annot
- Native midsurface:
- <freesurferDir>/surf/<hemi>.midthickness.surf.gii
- Volumetric parcellation files:
- <SubjectDir>/anat/volumetric/<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
- <SubjectDir>/xfms/<sub>_from-fsnative_to_nativepro_t1w_InverseWarped.nii.gz
- <SubjectDir>/xfms/<sub>_from-fsnative_to_nativepro_t1w_Warped.nii.gz
<parcellation> stands for the name of each of the 18 parcellations. <hemi> is either lh or rh.
-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_freesurfer 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:
$ mica-pipe -sub <subject_id> -out <outputDirectory> -bids <BIDS-directory> -GD
Docker command:
$ docker -GD
No optional arguments
Directories created or populated by -GD:
- <SubjectDir>/anat/surfaces/geo_dist/
One file per parcellation is generated by -GD:
- Square matrix of average parcel-to-parcel geodesic distances:
- <sub>_space-fsnative_atlas-<parcellation>_GD.txt
<parcellation> stands for the name of each of the 18 parcellations.
-Morphology¶
Here, surface-based morphological features are registered and smoothed on two distinct templates.
Prerequisites 🖐🏼
You need to run -proc_structural, -proc_freesurfer and -post_structural before this stage
- Register cortical thickness and curvature to fsaverage5 and conte69 templates
- Apply 10mm Gaussian smooth on template-mapped outputs
Terminal:
$ mica-pipe -sub <subject_id> -out <outputDirectory> -bids <BIDS-directory> -Morphology
Docker command:
$ docker -Morphology
No optional arguments
Directories created or populated by -Morphology:
- <SubjectDir>/anat/surfaces/morphology/
Files generated by -Morphology:
- Native surface space cortical thickness and curvature:
- <sub>_space-fsnative_desc-<hemi>_curvature.mgh
- <sub>_space-fsnative_desc-<hemi>_thickness.mgh
- fsaverage5-mapped cortical thickness and curvature:
- <sub>_space-fsaverage5_desc-<hemi>_curvature.mgh
- <sub>_space-fsaverage5_desc-<hemi>_thickness.mgh
- Smoothed fsaverage5-mapped cortical thickness and curvature:
- <sub>_space-fsaverage5_desc-<hemi>_curvature_10mm.mgh
- <sub>_space-fsaverage5_desc-<hemi>_thickness_10mm.mgh
- Conte69-mapped cortical thickness and curvature:
- <sub>_space-conte69-32k_desc-<hemi>_curvature.mgh
- <sub>_space-conte69-32k_desc-<hemi>_thickness.mgh
- Smoothed Conte69-mapped cortical thickness and curvature:
- <sub>_space-conte69-32k_desc-<hemi>_curvature_10mm.mgh
- <sub>_space-conte69-32k_desc-<hemi>_thickness_10mm.mgh
<hemi> is either lh or rh