smriprep.workflows.surfaces module
Surface preprocessing workflows.
sMRIPrep uses FreeSurfer to reconstruct surfaces from T1w/T2w structural images.
- smriprep.workflows.surfaces.init_autorecon_resume_wf(*, omp_nthreads, name='autorecon_resume_wf')[source]
Resume recon-all execution, assuming the -autorecon1 stage has been completed.
In order to utilize resources efficiently, this is broken down into seven sub-stages; after the first stage, the second and third stages may be run simultaneously, and the fifth and sixth stages may be run simultaneously, if resources permit; the fourth stage must be run prior to the fifth and sixth, and the seventh must be run after:
$ recon-all -sd <output dir>/freesurfer -subjid sub-<subject_label> \ -autorecon2-volonly $ recon-all -sd <output dir>/freesurfer -subjid sub-<subject_label> \ -autorecon-hemi lh -T2pial \ -noparcstats -noparcstats2 -noparcstats3 -nohyporelabel -nobalabels $ recon-all -sd <output dir>/freesurfer -subjid sub-<subject_label> \ -autorecon-hemi rh -T2pial \ -noparcstats -noparcstats2 -noparcstats3 -nohyporelabel -nobalabels $ recon-all -sd <output dir>/freesurfer -subjid sub-<subject_label> \ -cortribbon $ recon-all -sd <output dir>/freesurfer -subjid sub-<subject_label> \ -autorecon-hemi lh -nohyporelabel $ recon-all -sd <output dir>/freesurfer -subjid sub-<subject_label> \ -autorecon-hemi rh -nohyporelabel $ recon-all -sd <output dir>/freesurfer -subjid sub-<subject_label> \ -autorecon3
The parcellation statistics steps are excluded from the second and third stages, because they require calculation of the cortical ribbon volume (the fourth stage). Hypointensity relabeling is excluded from hemisphere-specific steps to avoid race conditions, as it is a volumetric operation.
- Workflow Graph
(Source code, png, svg, pdf)
- Inputs:
subjects_dir – FreeSurfer SUBJECTS_DIR
subject_id – FreeSurfer subject ID
use_T2 – Refine pial surface using T2w image
use_FLAIR – Refine pial surface using FLAIR image
- Outputs:
subjects_dir – FreeSurfer SUBJECTS_DIR
subject_id – FreeSurfer subject ID
- smriprep.workflows.surfaces.init_gifti_surface_wf(*, name='gifti_surface_wf')[source]
Prepare GIFTI surfaces from a FreeSurfer subjects directory.
If midthickness (or graymid) surfaces do not exist, they are generated and saved to the subject directory as
lh/rh.midthickness
. These, along with the gray/white matter boundary (lh/rh.white
), pial surfaces (lh/rh.pial
) and inflated surfaces (lh/rh.inflated
) are converted to GIFTI files. Additionally, the vertex coordinates arerecentered
to align with native T1w space.- Workflow Graph
(Source code, png, svg, pdf)
- Inputs:
subjects_dir – FreeSurfer SUBJECTS_DIR
subject_id – FreeSurfer subject ID
fsnative2t1w_xfm – LTA formatted affine transform file (inverse)
- Outputs:
midthickness – Left and right midthickness (or graymid) surface GIFTIs
pial – Left and right pial surface GIFTIs
white – Left and right white surface GIFTIs
inflated – Left and right inflated surface GIFTIs
surfaces – GIFTI surfaces for gray/white matter boundary, pial surface, midthickness (or graymid) surface, and inflated surfaces
thickness – Left and right cortical thickness GIFTIs
sulc – Left and right sulcal depth map GIFTIs
curv – Left and right curvature map GIFTIs
morphometrics – GIFTIs of cortical thickness, curvature, and sulcal depth
- smriprep.workflows.surfaces.init_morph_grayords_wf(grayord_density: Literal['91k', '170k'], name: str = 'morph_grayords_wf')[source]
Sample Grayordinates files onto the fsLR atlas.
Outputs are in CIFTI2 format.
- Workflow Graph
(Source code, png, svg, pdf)
- Parameters:
- Inputs:
- Outputs:
- smriprep.workflows.surfaces.init_msm_sulc_wf(*, sloppy: bool = False, name: str = 'msm_sulc_wf')[source]
Run MSMSulc registration to fsLR surfaces, per hemisphere.
- smriprep.workflows.surfaces.init_segs_to_native_wf(*, name='segs_to_native', segmentation='aseg')[source]
Get a segmentation from FreeSurfer conformed space into native T1w space.
- Workflow Graph
(Source code, png, svg, pdf)
- Parameters:
segmentation – The name of a segmentation (‘aseg’ or ‘aparc_aseg’ or ‘wmparc’)
- Inputs:
in_file – Anatomical, merged T1w image after INU correction
subjects_dir – FreeSurfer SUBJECTS_DIR
subject_id – FreeSurfer subject ID
fsnative2t1w_xfm – LTA-style affine matrix translating from FreeSurfer-conformed subject space to T1w
- Outputs:
out_file – The selected segmentation, after resampling in native space
- smriprep.workflows.surfaces.init_sphere_reg_wf(*, msm_sulc: bool = False, sloppy: bool = False, name: str = 'sphere_reg_wf')[source]
Generate GIFTI registration files to fsLR space
- smriprep.workflows.surfaces.init_surface_recon_wf(*, omp_nthreads, hires, name='surface_recon_wf')[source]
Reconstruct anatomical surfaces using FreeSurfer’s
recon-all
.Reconstruction is performed in three phases. The first phase initializes the subject with T1w and T2w (if available) structural images and performs basic reconstruction (
autorecon1
) with the exception of skull-stripping. For example, a subject with only one session with T1w and T2w images would be processed by the following command:$ recon-all -sd <output dir>/freesurfer -subjid sub-<subject_label> \ -i <bids-root>/sub-<subject_label>/anat/sub-<subject_label>_T1w.nii.gz \ -T2 <bids-root>/sub-<subject_label>/anat/sub-<subject_label>_T2w.nii.gz \ -autorecon1 \ -noskullstrip -noT2pial -noFLAIRpial
The second phase imports an externally computed skull-stripping mask. This workflow refines the external brainmask using the internal mask implicit the the FreeSurfer’s
aseg.mgz
segmentation, to reconcile ANTs’ and FreeSurfer’s brain masks.First, the
aseg.mgz
mask from FreeSurfer is refined in two steps, using binary morphological operations:With a binary closing operation the sulci are included into the mask. This results in a smoother brain mask that does not exclude deep, wide sulci.
Fill any holes (typically, there could be a hole next to the pineal gland and the corpora quadrigemina if the great cerebral brain is segmented out).
Second, the brain mask is grown, including pixels that have a high likelihood to the GM tissue distribution:
Dilate and subtract the brain mask, defining the region to search for candidate pixels that likely belong to cortical GM.
Pixels found in the search region that are labeled as GM by ANTs (during
antsBrainExtraction.sh
) are directly added to the new mask.Otherwise, estimate GM tissue parameters locally in patches of
ww
size, and test the likelihood of the pixel to belong in the GM distribution.
This procedure is inspired on mindboggle’s solution to the problem: https://github.com/nipy/mindboggle/blob/7f91faaa7664d820fe12ccc52ebaf21d679795e2/mindboggle/guts/segment.py#L1660
The final phase resumes reconstruction, using the T2w image to assist in finding the pial surface, if available. See
init_autorecon_resume_wf()
for details.Memory annotations for FreeSurfer are based off their documentation. They specify an allocation of 4GB per subject. Here we define 5GB to have a certain margin.
- Workflow Graph
(Source code, png, svg, pdf)
- Parameters:
omp_nthreads (int) – Maximum number of threads an individual process may use
hires (bool) – Enable sub-millimeter preprocessing in FreeSurfer
- Inputs:
t1w – List of T1-weighted structural images
t2w – List of T2-weighted structural images (only first used)
flair – List of FLAIR images
skullstripped_t1 – Skull-stripped T1-weighted image (or mask of image)
ants_segs – Brain tissue segmentation from ANTS
antsBrainExtraction.sh
corrected_t1 – INU-corrected, merged T1-weighted image
subjects_dir – FreeSurfer SUBJECTS_DIR
subject_id – FreeSurfer subject ID
- Outputs:
subjects_dir – FreeSurfer SUBJECTS_DIR
subject_id – FreeSurfer subject ID
t1w2fsnative_xfm – LTA-style affine matrix translating from T1w to FreeSurfer-conformed subject space
fsnative2t1w_xfm – LTA-style affine matrix translating from FreeSurfer-conformed subject space to T1w
surfaces – GIFTI surfaces for gray/white matter boundary, pial surface, midthickness (or graymid) surface, and inflated surfaces
out_brainmask – Refined brainmask, derived from FreeSurfer’s
aseg
volumeout_aseg – FreeSurfer’s aseg segmentation, in native T1w space
out_aparc – FreeSurfer’s aparc+aseg segmentation, in native T1w space
morphometrics – GIFTIs of cortical thickness, curvature, and sulcal depth