.. _structproc: .. title:: Structural processing ********************* Structural processing ********************* .. contents:: 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 ============================================================ .. image:: sankey_proc_structural.png :align: center 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*. .. admonition:: Nativepro?! ๐Ÿคจ Nativepro stands for **native** **pro**\cessing 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. .. image:: proc_structural.png :scale: 85 % :align: center .. tabs:: .. tab:: Processing steps - 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) .. tab:: Usage **Terminal:** .. parsed-literal:: $ micapipe **-sub** **-out** **-bids** **-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. .. tabularcolumns:: |>{\centering\arraybackslash}\X{1}{5}|>{\raggedleft\arraybackslash}\X{2}{5}| .. list-table:: :widths: 10 500 :header-rows: 1 :class: tight-table * - **Optional argument** - **Description** * - ``-T1wStr`` ```` - 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. * - ``-uni`` - Special workflow to use the UNI-T1map image as the structural reference (eg. 7T UNI-T1map). Default = no processing of UNI-T1maps. * - ``-mf`` ```` - 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//anat* directory, only the MRI volume containing the string ``run-02_T1w`` will be processed: .. code-block:: bash :caption: Example :linenos: :emphasize-lines: 2 micapipe -sub -out -bids \ -proc_structural -T1wStr run-02_T1w .. tab:: Outputs Directories created or populated by **-proc_structural** will be under each ``SubjectDir`` which is ``/micapipe/``. .. parsed-literal:: - /anat - /xfm Files generated by **-proc_structural**: .. parsed-literal:: - **Main structural scan:** - /anat/_space-nativepro_T1w.nii.gz - **Brain extracted main structural scan**: - */anat/_space-nativepro_T1w_brain.nii.gz* - **Brain-mask for main structural scan**: - */anat/_space-nativepro_T1w_brain_mask.nii.gz* - **FSL FAST outputs** stored in */anat/*: - _space-nativepro_T1w_brain_pve_0.nii.gz - _space-nativepro_T1w_brain_pve_1.nii.gz - _space-nativepro_T1w_brain_pve_2.nii.gz - **Main structural scan non-linear transformations to MNI152 0.8mm:** */xfm/* - _from-nativepro_brain_to-MNI152_0.8mm_mode-image_desc-SyN_0GenericAffine.mat - _from-nativepro_brain_to-MNI152_0.8mm_mode-image_desc-SyN_1InverseWarp.nii.gz - _from-nativepro_brain_to-MNI152_0.8mm_mode-image_desc-SyN_1Warp.nii.gz - _from-nativepro_brain_to-MNI152_0.8mm_mode-image_desc-SyN_InverseWarped.nii.gz - **Main structural scan non-linear transformations to MNI152 2mm:** */xfm/* - _from-nativepro_brain_to-MNI152_2mm_mode-image_desc-SyN_0GenericAffine.mat - _from-nativepro_brain_to-MNI152_2mm_mode-image_desc-SyN_1InverseWarp.nii.gz - _from-nativepro_brain_to-MNI152_2mm_mode-image_desc-SyN_1Warp.nii.gz - _from-nativepro_brain_to-MNI152_2mm_mode-image_desc-SyN_InverseWarped.nii.gz - **Final 5ttgen output**: - */anat/_space-nativepro_T1w_5TT.nii.gz* - **Json cards** are in */anat/*: - _space-nativepro_T1w_brain_mask.json - _space-nativepro_T1w.json .. tab:: Multiplying factor (-mf) .. image:: denoise_mp2rage.png :align: center -proc_surf ============================================================ .. image:: sankey_proc_surf.png :align: center This modules performs cortical surface segmentation from all native T1w acquisitions stored in the subject's BIDS directory. .. admonition:: 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 .. image:: proc_surf.png :scale: 85 % :align: center .. tabs:: .. tab:: Processing steps - Run surface reconstruction (fastsurfer or freesurfer) pipeline will all T1-weighted scans found in raw data directory .. tab:: Usage **Terminal:** .. parsed-literal:: $ micapipe **-sub** **-out** **-bids** **-proc_surf** **** **Optional arguments** ``-proc_surf`` has a few optional arguments, including an option for T1w scan selection as in ``proc_volumetric``. .. list-table:: :widths: 10 500 :header-rows: 1 :class: tight-table * - **Optional argument** - **Description** * - ``-T1wStr`` ```` - Same option as in ``-proc_structural``, this will allow to manually select the main scan(s) for structural processing. * - ``-freesurfer`` ```` - Use this option to reconstruct the cortical surface with Freesurfer 7. Default surface reconstruction uses 'FastSurfer' * - ``-surf_dir`` ```` - 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. * - ``-fs_licence`` - 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 * - ``-T1`` - 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. .. tab:: Outputs Directories created or populated by **-proc_surf**: .. parsed-literal:: - /freesurfer/ - /fastsurfer/ Files generated by **-proc_surf**: .. parsed-literal:: - A list of all recon-all output files can be found here: `ReconAllOutputFiles `_. -post_structural ============================================================ .. image:: sankey_post_structural.png :align: center 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. .. admonition:: Prerequisites ๐Ÿ–๐Ÿผ You need to run ``-proc_structural`` and ``-proc_surf`` before this stage. .. image:: post_structural.png :scale: 85 % :align: center .. tabs:: .. tab:: Processing steps - 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 .. tab:: Usage **Terminal:** .. parsed-literal:: $ micapipe **-sub** **-out** **-bids** **-post_structural** **** **Optional arguments**: ``-post_structural`` only has one optional argument: .. list-table:: :widths: 10 500 :header-rows: 1 :class: tight-table * - **Optional argument** - **Description** * - ``-atlas`` ```` - 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: .. hlist:: :columns: 3 - aparc-a2009s - aparc - economo - glasser-360 - schaefer-1000 - schaefer-100 - schaefer-200 - schaefer-300 - schaefer-400 - schaefer-500 - schaefer-600 - schaefer-700 - schaefer-800 - schaefer-900 - vosdewael-100 - vosdewael-200 - vosdewael-300 - vosdewael-400 The next example will only process the three selected parcellations (``schaefer-200,economo,aparc``) .. code-block:: bash :caption: Example :linenos: :emphasize-lines: 2 micapipe -sub -out -bids \ -post_structural -atlas schaefer-200,economo,aparc .. admonition:: 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. .. tab:: Outputs Directories created or populated by ``-post_structural`` will be under each ``SubjectDir`` which is ``/micapipe/`` and ``freesurferDir`` which is ``/freesurfer/``: .. parsed-literal:: - /anat - /surf - /maps - /parc - /xfm Files generated by ``-post_structural``: .. parsed-literal:: - Main structural scan (nativepro) in FreeSurfer space: - */anat/_space-fsnative_T1w.nii.gz* - Surface files resampled to fsaverage5, fsLR-32k and fsLR-5k templates, stored in /surf: - Pial - *_hemi-L_space-nativepro_surf-