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')

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
../_images/smriprep-workflows-surfaces-1.png

(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')

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.smoothwm), pial sufaces (lh/rh.pial) and inflated surfaces (lh/rh.inflated) are converted to GIFTI files. Additionally, the vertex coordinates are recentered to align with native T1w space.

Workflow Graph
../_images/smriprep-workflows-surfaces-2.png

(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

surfaces – GIFTI surfaces for gray/white matter boundary, pial surface, midthickness (or graymid) surface, and inflated surfaces

smriprep.workflows.surfaces.init_segs_to_native_wf(*, name='segs_to_native', segmentation='aseg')

Get a segmentation from FreeSurfer conformed space into native T1w space.

Workflow Graph
../_images/smriprep-workflows-surfaces-3.png

(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_surface_recon_wf(*, omp_nthreads, hires, name='surface_recon_wf')

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

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:

  1. 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.

  2. 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:

  1. Dilate and substract the brain mask, defining the region to search for candidate pixels that likely belong to cortical GM.

  2. Pixels found in the search region that are labeled as GM by ANTs (during antsBrainExtraction.sh) are directly added to the new mask.

  3. 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
../_images/smriprep-workflows-surfaces-4.png

(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 volume

  • out_aseg – FreeSurfer’s aseg segmentation, in native T1w space

  • out_aparc – FreeSurfer’s aparc+aseg segmentation, in native T1w space