smriprep.workflows.surfaces module

Surface preprocessing workflows.

sMRIPrep uses FreeSurfer to reconstruct surfaces from T1w/T2w structural images.

smriprep.workflows.surfaces.init_anat_ribbon_wf(name='anat_ribbon_wf')[source]

Create anatomical ribbon mask

Workflow Graph

(Source code, png, svg, pdf)

Inputs:

white – Left and right gray/white surfaces (as GIFTI files)
pial – Left and right pial surfaces (as GIFTI files)
ref_file – Reference image (one 3D volume) to define the target space

Outputs:

anat_ribbon – Cortical gray matter mask, sampled into ref_file space

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_fsLR_reg_wf(*, name='fsLR_reg_wf')[source]: Generate GIFTI registration files to fsLR space

smriprep.workflows.surfaces.init_gifti_morphometrics_wf(*, morphometrics: list[str] = ('thickness', 'curv', 'sulc'), name: str = 'gifti_morphometrics_wf')[source]

Prepare GIFTI shape files from morphometrics found in a FreeSurfer subjects directory.

The default morphometrics are lh/rh.thickness, lh/rh.curv, and lh/rh.sulc.

Workflow Graph: (Source code, png, svg, pdf)

Inputs:

subjects_dir – FreeSurfer SUBJECTS_DIR
subject_id – FreeSurfer subject ID

Outputs:

morphometrics – GIFTI shape files for all requested morphometrics
``<morphometric>`` – Left and right GIFTIs for each morphometry type passed to morphometrics

smriprep.workflows.surfaces.init_gifti_surfaces_wf(*, surfaces: list[str] = ('pial', 'midthickness', 'inflated', 'white'), to_scanner: bool = True, name: str = 'gifti_surface_wf')[source]

Prepare GIFTI surfaces from a FreeSurfer subjects directory.

The default surfaces are lh/rh.pial, lh/rh.midthickness, lh/rh.inflated, and lh/rh.white.

Vertex coordinates are transformed to align with native anatomical space when fsnative2anat_xfm is provided.

Workflow Graph: (Source code, png, svg, pdf)

Inputs:

subjects_dir – FreeSurfer SUBJECTS_DIR
subject_id – FreeSurfer subject ID
fsnative2anat_xfm – LTA formatted affine transform file

Outputs:

surfaces – GIFTI surfaces for all requested surfaces
``<surface>`` – Left and right GIFTIs for each surface passed to surfaces

smriprep.workflows.surfaces.init_hcp_morphometrics_wf(*, omp_nthreads: int, name: str = 'hcp_morphometrics_wf') → LiterateWorkflow[source]

Convert FreeSurfer-style morphometrics to HCP-style.

The HCP uses different conventions for curvature and sulcal depth from FreeSurfer, and performs some geometric preprocessing steps to get final metrics and a subject-specific cortical ROI.

Workflow Graph

../_images/smriprep-workflows-surfaces-5.png

(Source code, png, svg, pdf)

Parameters:

omp_nthreads – Maximum number of threads an individual process may use

Inputs:

subject_id – FreeSurfer subject ID
thickness – FreeSurfer thickness file in GIFTI format
curv – FreeSurfer curvature file in GIFTI format
sulc – FreeSurfer sulcal depth file in GIFTI format

Outputs:

thickness – HCP-style thickness file in GIFTI format
curv – HCP-style curvature file in GIFTI format
sulc – HCP-style sulcal depth file in GIFTI format
roi – HCP-style cortical ROI file in GIFTI format

smriprep.workflows.surfaces.init_morph_grayords_wf(grayord_density: Literal['91k', '170k'], omp_nthreads: int, 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:

grayord_density (str) – Either 91k or 170k, representing the total of vertices or grayordinates.
name (str) – Unique name for the subworkflow (default: "morph_grayords_wf")

Inputs:

curv – HCP-style curvature file in GIFTI format
sulc – HCP-style sulcal depth file in GIFTI format
thickness – HCP-style thickness file in GIFTI format
roi – HCP-style cortical ROI file in GIFTI format
midthickness – GIFTI surface mesh corresponding to the midthickness surface
sphere_reg_fsLR – GIFTI surface mesh corresponding to the subject’s fsLR registration sphere

Outputs:

curv_fsLR – HCP-style curvature file in CIFTI-2 format, resampled to fsLR
curv_metadata – Path to JSON file containing metadata corresponding to curv_fsLR
sulc_fsLR – HCP-style sulcal depth file in CIFTI-2 format, resampled to fsLR
sulc_metadata – Path to JSON file containing metadata corresponding to sulc_fsLR
thickness_fsLR – HCP-style thickness file in CIFTI-2 format, resampled to fsLR

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_refinement_wf(*, image_type: Literal['T1w', 'T2w'] = 'T1w', name: str = 'refinement_wf') → LiterateWorkflow[source]

Refine ANTs brain extraction with FreeSurfer segmentation

Workflow Graph: (Source code, png, svg, pdf)

Inputs:

subjects_dir – FreeSurfer SUBJECTS_DIR
subject_id – FreeSurfer subject ID
fsnative2anat_xfm – LTA-style affine matrix translating from FreeSurfer-conformed subject space to anatomical
reference_image – Input
ants_segs – Brain tissue segmentation from ANTS antsBrainExtraction.sh
subjects_dir – FreeSurfer SUBJECTS_DIR
subject_id – FreeSurfer subject ID

Outputs:

out_brainmask – Refined brainmask, derived from FreeSurfer’s aseg volume

See also

init_gifti_surface_wf()

smriprep.workflows.surfaces.init_surface_recon_wf(*, omp_nthreads: int, hires: bool, fs_no_resume: bool, precomputed: dict, 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
fs_no_resume (bool) – use precomputed freesurfer without attempting to resume (eg. for longitudinal base or fastsurfer)

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)
subjects_dir – FreeSurfer SUBJECTS_DIR
subject_id – FreeSurfer subject ID

Outputs:

subjects_dir – FreeSurfer SUBJECTS_DIR
subject_id – FreeSurfer subject ID
fsnative2t1w_xfm – LTA-style affine matrix translating from FreeSurfer-conformed subject space to T1w