API

Workflows

fMRIprep base processing workflows

fmriprep.workflows.base.init_fmriprep_wf(subject_list, task_id, run_uuid, ignore, debug, low_mem, anat_only, longitudinal, omp_nthreads, skull_strip_template, work_dir, output_dir, bids_dir, freesurfer, output_spaces, template, medial_surface_nan, hires, use_bbr, bold2t1w_dof, fmap_bspline, fmap_demean, use_syn, force_syn, use_aroma, ignore_aroma_err, output_grid_ref)[source]

This workflow organizes the execution of FMRIPREP, with a sub-workflow for each subject.

If FreeSurfer is to be used, a FreeSurfer derivatives folder is created and populated with any needed template subjects.

(Source code)

Parameters

subject_list : list
List of subject labels
task_id : str or None
Task ID of BOLD series to preprocess, or None to preprocess all
run_uuid : str
Unique identifier for execution instance
ignore : list
Preprocessing steps to skip (may include “slicetiming”, “fieldmaps”)
debug : bool
Enable debugging outputs
low_mem : bool
Write uncompressed .nii files in some cases to reduce memory usage
anat_only : bool
Disable functional workflows
longitudinal : bool
Treat multiple sessions as longitudinal (may increase runtime) See sub-workflows for specific differences
omp_nthreads : int
Maximum number of threads an individual process may use
skull_strip_template : str
Name of ANTs skull-stripping template (‘OASIS’ or ‘NKI’)
work_dir : str
Directory in which to store workflow execution state and temporary files
output_dir : str
Directory in which to save derivatives
bids_dir : str
Root directory of BIDS dataset
freesurfer : bool
Enable FreeSurfer surface reconstruction (may increase runtime)
output_spaces : list

List of output spaces functional images are to be resampled to. Some parts of pipeline will only be instantiated for some output spaces.

Valid spaces:

  • T1w
  • template
  • fsnative
  • fsaverage (or other pre-existing FreeSurfer templates)
template : str
Name of template targeted by ‘template’ output space
medial_surface_nan : bool
Replace medial wall values with NaNs on functional GIFTI files
hires : bool
Enable sub-millimeter preprocessing in FreeSurfer
use_bbr : bool or None
Enable/disable boundary-based registration refinement. If None, test BBR result for distortion before accepting.
bold2t1w_dof : 6, 9 or 12
Degrees-of-freedom for BOLD-T1w registration
fmap_bspline : bool
Experimental: Fit B-Spline field using least-squares
fmap_demean : bool
Demean voxel-shift map during unwarp
use_syn : bool
Experimental: Enable ANTs SyN-based susceptibility distortion correction (SDC). If fieldmaps are present and enabled, this is not run, by default.
force_syn : bool
Temporary: Always run SyN-based SDC
use_aroma : bool
Perform ICA-AROMA on MNI-resampled functional series
ignore_aroma_err : bool
Do not fail on ICA-AROMA errors
output_grid_ref : str or None
Path of custom reference image for normalization
fmriprep.workflows.base.init_single_subject_wf(subject_id, task_id, name, ignore, debug, low_mem, anat_only, longitudinal, omp_nthreads, skull_strip_template, reportlets_dir, output_dir, bids_dir, freesurfer, output_spaces, template, medial_surface_nan, hires, use_bbr, bold2t1w_dof, fmap_bspline, fmap_demean, use_syn, force_syn, output_grid_ref, use_aroma, ignore_aroma_err)[source]

This workflow organizes the preprocessing pipeline for a single subject. It collects and reports information about the subject, and prepares sub-workflows to perform anatomical and functional preprocessing.

Anatomical preprocessing is performed in a single workflow, regardless of the number of sessions. Functional preprocessing is performed using a separate workflow for each individual BOLD series.

../_images/index-2.png

(Source code, png, svg, pdf)

Parameters

subject_id : str
List of subject labels
task_id : str or None
Task ID of BOLD series to preprocess, or None to preprocess all
name : str
Name of workflow
ignore : list
Preprocessing steps to skip (may include “slicetiming”, “fieldmaps”)
debug : bool
Enable debugging outputs
low_mem : bool
Write uncompressed .nii files in some cases to reduce memory usage
anat_only : bool
Disable functional workflows
longitudinal : bool
Treat multiple sessions as longitudinal (may increase runtime) See sub-workflows for specific differences
omp_nthreads : int
Maximum number of threads an individual process may use
skull_strip_template : str
Name of ANTs skull-stripping template (‘OASIS’ or ‘NKI’)
reportlets_dir : str
Directory in which to save reportlets
output_dir : str
Directory in which to save derivatives
bids_dir : str
Root directory of BIDS dataset
freesurfer : bool
Enable FreeSurfer surface reconstruction (may increase runtime)
output_spaces : list

List of output spaces functional images are to be resampled to. Some parts of pipeline will only be instantiated for some output spaces.

Valid spaces:

  • T1w
  • template
  • fsnative
  • fsaverage (or other pre-existing FreeSurfer templates)
template : str
Name of template targeted by ‘template’ output space
medial_surface_nan : bool
Replace medial wall values with NaNs on functional GIFTI files
hires : bool
Enable sub-millimeter preprocessing in FreeSurfer
use_bbr : bool or None
Enable/disable boundary-based registration refinement. If None, test BBR result for distortion before accepting.
bold2t1w_dof : 6, 9 or 12
Degrees-of-freedom for BOLD-T1w registration
fmap_bspline : bool
Experimental: Fit B-Spline field using least-squares
fmap_demean : bool
Demean voxel-shift map during unwarp
use_syn : bool
Experimental: Enable ANTs SyN-based susceptibility distortion correction (SDC). If fieldmaps are present and enabled, this is not run, by default.
force_syn : bool
Temporary: Always run SyN-based SDC
output_grid_ref : str or None
Path of custom reference image for normalization
use_aroma : bool
Perform ICA-AROMA on MNI-resampled functional series
ignore_aroma_err : bool
Do not fail on ICA-AROMA errors

Inputs

subjects_dir
FreeSurfer SUBJECTS_DIR

Anatomical reference preprocessing workflows

fmriprep.workflows.anatomical.init_anat_preproc_wf(skull_strip_template, output_spaces, template, debug, freesurfer, longitudinal, omp_nthreads, hires, reportlets_dir, output_dir, name='anat_preproc_wf')[source]

This workflow controls the anatomical preprocessing stages of FMRIPREP.

This includes:

  • Creation of a structural template
  • Skull-stripping and bias correction
  • Tissue segmentation
  • Normalization
  • Surface reconstruction with FreeSurfer
../_images/index-3.png

(Source code, png, svg, pdf)

Parameters

skull_strip_template : str
Name of ANTs skull-stripping template (‘OASIS’ or ‘NKI’)
output_spaces : list

List of output spaces functional images are to be resampled to.

Some pipeline components will only be instantiated for some output spaces.

Valid spaces:

  • T1w
  • template
  • fsnative
  • fsaverage (or other pre-existing FreeSurfer templates)
template : str
Name of template targeted by ‘template’ output space
debug : bool
Enable debugging outputs
freesurfer : bool
Enable FreeSurfer surface reconstruction (may increase runtime)
longitudinal : bool
Create unbiased structural template, regardless of number of inputs (may increase runtime)
omp_nthreads : int
Maximum number of threads an individual process may use
hires : bool
Enable sub-millimeter preprocessing in FreeSurfer
reportlets_dir : str
Directory in which to save reportlets
output_dir : str
Directory in which to save derivatives
name : str, optional
Workflow name (default: anat_preproc_wf)

Inputs

t1w
List of T1-weighted structural images
t2w
List of T2-weighted structural images
subjects_dir
FreeSurfer SUBJECTS_DIR

Outputs

t1_preproc
Bias-corrected structural template, defining T1w space
t1_brain
Skull-stripped t1_preproc
t1_mask
Mask of the skull-stripped template image
t1_seg
Segmentation of preprocessed structural image, including gray-matter (GM), white-matter (WM) and cerebrospinal fluid (CSF)
t1_tpms
List of tissue probability maps in T1w space
t1_2_mni
T1w template, normalized to MNI space
t1_2_mni_forward_transform
ANTs-compatible affine-and-warp transform file
t1_2_mni_reverse_transform
ANTs-compatible affine-and-warp transform file (inverse)
mni_mask
Mask of skull-stripped template, in MNI space
mni_seg
Segmentation, resampled into MNI space
mni_tpms
List of tissue probability maps in MNI space
subjects_dir
FreeSurfer SUBJECTS_DIR
subject_id
FreeSurfer subject ID
t1_2_fsnative_forward_transform
LTA-style affine matrix translating from T1w to FreeSurfer-conformed subject space
t1_2_fsnative_reverse_transform
LTA-style affine matrix translating from FreeSurfer-conformed subject space to T1w
surfaces
GIFTI surfaces (gray/white boundary, midthickness, pial, inflated)

Subworkflows

fmriprep.workflows.anatomical.init_skullstrip_ants_wf(skull_strip_template, debug, omp_nthreads, name='skullstrip_ants_wf')[source]

This workflow performs skull-stripping using ANTs’ BrainExtraction.sh

../_images/index-4.png

(Source code, png, svg, pdf)

Parameters

skull_strip_template : str
Name of ANTs skull-stripping template (‘OASIS’ or ‘NKI’)
debug : bool
Enable debugging outputs
omp_nthreads : int
Maximum number of threads an individual process may use

Inputs

in_file
T1-weighted structural image to skull-strip

Outputs

bias_corrected
Bias-corrected in_file, before skull-stripping
out_file
Skull-stripped in_file
out_mask
Binary mask of the skull-stripped in_file
out_report
Reportlet visualizing quality of skull-stripping

Surface preprocessing

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

fmriprep.workflows.anatomical.init_surface_recon_wf(omp_nthreads, hires, name='surface_recon_wf')[source]

This workflow reconstructs 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. 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.

../_images/index-5.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)
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
t1_2_fsnative_forward_transform
LTA-style affine matrix translating from T1w to FreeSurfer-conformed subject space
t1_2_fsnative_reverse_transform
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_report
Reportlet visualizing quality of surface alignment

Subworkflows

fmriprep.workflows.anatomical.init_autorecon_resume_wf(omp_nthreads, name='autorecon_resume_wf')[source]

This workflow resumes recon-all execution, assuming the -autorecon1 stage has been completed.

In order to utilize resources efficiently, this is broken down into five sub-stages; after the first stage, the second and third stages may be run simultaneously, and the fourth and fifth stages may be run simultaneously, if resources permit:

$ 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 \
    -noparcstats -nocortparc2 -noparcstats2 -nocortparc3 \
    -noparcstats3 -nopctsurfcon -nohyporelabel -noaparc2aseg \
    -noapas2aseg -nosegstats -nowmparc -nobalabels
$ recon-all -sd <output dir>/freesurfer -subjid sub-<subject_label> \
    -autorecon-hemi rh \
    -noparcstats -nocortparc2 -noparcstats2 -nocortparc3 \
    -noparcstats3 -nopctsurfcon -nohyporelabel -noaparc2aseg \
    -noapas2aseg -nosegstats -nowmparc -nobalabels
$ recon-all -sd <output dir>/freesurfer -subjid sub-<subject_label> \
    -autorecon3 -hemi lh -T2pial
$ recon-all -sd <output dir>/freesurfer -subjid sub-<subject_label> \
    -autorecon3 -hemi rh -T2pial

The excluded steps in the second and third stages (-no<option>) are not fully hemisphere independent, and are therefore postponed to the final two stages.

../_images/index-6.png

(Source code, png, svg, pdf)

Inputs

subjects_dir
FreeSurfer SUBJECTS_DIR
subject_id
FreeSurfer subject ID
use_T2
Refine pial surface using T2w images

Outputs

subjects_dir
FreeSurfer SUBJECTS_DIR
subject_id
FreeSurfer subject ID
out_report
Reportlet visualizing quality of surface alignment
fmriprep.workflows.anatomical.init_gifti_surface_wf(name='gifti_surface_wf')[source]

This workflow prepares 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.

../_images/index-7.png

(Source code, png, svg, pdf)

Inputs

subjects_dir
FreeSurfer SUBJECTS_DIR
subject_id
FreeSurfer subject ID
t1_2_fsnative_reverse_transform
LTA formatted affine transform file (inverse)

Outputs

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

Pre-processing fMRI - BOLD signal workflows

Orchestrating the BOLD-preprocessing workflow

fmriprep.workflows.bold.base.init_func_preproc_wf(bold_file, ignore, freesurfer, use_bbr, bold2t1w_dof, reportlets_dir, output_spaces, template, output_dir, omp_nthreads, fmap_bspline, fmap_demean, use_syn, force_syn, use_aroma, ignore_aroma_err, medial_surface_nan, debug, low_mem, output_grid_ref, layout=None)[source]

This workflow controls the functional preprocessing stages of FMRIPREP.

../_images/index-8.png

(Source code, png, svg, pdf)

Parameters

bold_file : str
BOLD series NIfTI file
ignore : list
Preprocessing steps to skip (may include “slicetiming”, “fieldmaps”)
freesurfer : bool
Enable FreeSurfer functional registration (bbregister) and resampling BOLD series to FreeSurfer surface meshes.
use_bbr : bool or None
Enable/disable boundary-based registration refinement. If None, test BBR result for distortion before accepting.
bold2t1w_dof : 6, 9 or 12
Degrees-of-freedom for BOLD-T1w registration
reportlets_dir : str
Directory in which to save reportlets
output_spaces : list

List of output spaces functional images are to be resampled to. Some parts of pipeline will only be instantiated for some output spaces.

Valid spaces:

  • T1w
  • template
  • fsnative
  • fsaverage (or other pre-existing FreeSurfer templates)
template : str
Name of template targeted by ‘template’ output space
output_dir : str
Directory in which to save derivatives
omp_nthreads : int
Maximum number of threads an individual process may use
fmap_bspline : bool
Experimental: Fit B-Spline field using least-squares
fmap_demean : bool
Demean voxel-shift map during unwarp
use_syn : bool
Experimental: Enable ANTs SyN-based susceptibility distortion correction (SDC). If fieldmaps are present and enabled, this is not run, by default.
force_syn : bool
Temporary: Always run SyN-based SDC
use_aroma : bool
Perform ICA-AROMA on MNI-resampled functional series
ignore_aroma_err : bool
Do not fail on ICA-AROMA errors
medial_surface_nan : bool
Replace medial wall values with NaNs on functional GIFTI files
debug : bool
Enable debugging outputs
low_mem : bool
Write uncompressed .nii files in some cases to reduce memory usage
output_grid_ref : str or None
Path of custom reference image for normalization
layout : BIDSLayout
BIDSLayout structure to enable metadata retrieval

Inputs

bold_file
BOLD series NIfTI file
t1_preproc
Bias-corrected structural template image
t1_brain
Skull-stripped t1_preproc
t1_mask
Mask of the skull-stripped template image
t1_seg
Segmentation of preprocessed structural image, including gray-matter (GM), white-matter (WM) and cerebrospinal fluid (CSF)
t1_tpms
List of tissue probability maps in T1w space
t1_2_mni_forward_transform
ANTs-compatible affine-and-warp transform file
t1_2_mni_reverse_transform
ANTs-compatible affine-and-warp transform file (inverse)
subjects_dir
FreeSurfer SUBJECTS_DIR
subject_id
FreeSurfer subject ID
t1_2_fsnative_forward_transform
LTA-style affine matrix translating from T1w to FreeSurfer-conformed subject space
t1_2_fsnative_reverse_transform
LTA-style affine matrix translating from FreeSurfer-conformed subject space to T1w

Outputs

bold_t1
BOLD series, resampled to T1w space
bold_mask_t1
BOLD series mask in T1w space
bold_mni
BOLD series, resampled to template space
bold_mask_mni
BOLD series mask in template space
confounds
TSV of confounds
surfaces
BOLD series, resampled to FreeSurfer surfaces
aroma_noise_ics
Noise components identified by ICA-AROMA
melodic_mix
FSL MELODIC mixing matrix

Subworkflows

fmriprep.workflows.bold.base.init_func_reports_wf(reportlets_dir, freesurfer, use_aroma, use_syn, name='func_reports_wf')[source]

Set up a battery of datasinks to store reports in the right location

fmriprep.workflows.bold.base.init_func_derivatives_wf(output_dir, output_spaces, template, freesurfer, use_aroma, name='func_derivatives_wf')[source]

Set up a battery of datasinks to store derivatives in the right location

Utility workflows

fmriprep.workflows.bold.util.init_bold_reference_wf(omp_nthreads, bold_file=None, name='bold_reference_wf')[source]

This workflow generates reference BOLD images for a series

The raw reference image is the target of HMC, and a contrast-enhanced reference is the subject of distortion correction, as well as boundary-based registration to T1w and template spaces.

../_images/index-9.png

(Source code, png, svg, pdf)

Parameters

bold_file : str
BOLD series NIfTI file
omp_nthreads : int
Maximum number of threads an individual process may use
name : str
Name of workflow (default: bold_reference_wf)

Inputs

bold_file
BOLD series NIfTI file

Outputs

bold_file
Validated BOLD series NIfTI file
raw_ref_image
Reference image to which BOLD series is motion corrected
skip_vols
Number of non-steady-state volumes detected at beginning of bold_file
ref_image
Contrast-enhanced reference image
ref_image_brain
Skull-stripped reference image
bold_mask
Skull-stripping mask of reference image
bold_mask_report
Reportlet showing quality of masking
validation_report
HTML reportlet indicating whether bold_file had a valid affine

Subworkflows

  • init_enhance_and_skullstrip_wf()
fmriprep.workflows.bold.util.init_enhance_and_skullstrip_bold_wf(name='enhance_and_skullstrip_bold_wf', omp_nthreads=1)[source]

This workflow takes in a BOLD volume, and attempts to enhance the contrast between gray and white matter, and skull-stripping the result.

../_images/index-10.png

(Source code, png, svg, pdf)

Inputs

in_file
BOLD image (single volume)

Outputs

bias_corrected_file
the in_file after N4BiasFieldCorrection
skull_stripped_file
the bias_corrected_file after skull-stripping
mask_file
mask of the skull-stripped input file
out_report
reportlet for the skull-stripping
fmriprep.workflows.bold.util.init_skullstrip_bold_wf(name='skullstrip_bold_wf')[source]

This workflow applies skull-stripping to a BOLD image.

It is intended to be used on an image that has previously been bias-corrected with init_enhance_and_skullstrip_bold_wf()

../_images/index-11.png

(Source code, png, svg, pdf)

Inputs

in_file
BOLD image (single volume)

Outputs

skull_stripped_file
the in_file after skull-stripping
mask_file
mask of the skull-stripped input file
out_report
reportlet for the skull-stripping

Head-Motion Estimation and Correction (HMC) of BOLD images

fmriprep.workflows.bold.hmc.init_bold_hmc_wf(mem_gb, omp_nthreads, name='bold_hmc_wf')[source]

This workflow performs HMC over the input BOLD image.

../_images/index-12.png

(Source code, png, svg, pdf)

Parameters

mem_gb : float
Size of BOLD file in GB
omp_nthreads : int
Maximum number of threads an individual process may use
name : str
Name of workflow (default: bold_hmc_wf)

Inputs

bold_file
BOLD series NIfTI file
raw_ref_image
Reference image to which BOLD series is motion corrected

Outputs

bold_split
Individual 3D volumes, not motion corrected
xforms
ITKTransform file aligning each volume to ref_image
movpar_file
MCFLIRT motion parameters, normalized to SPM format (X, Y, Z, Rx, Ry, Rz)

Slice-Timing Correction (STC) of BOLD images

fmriprep.workflows.bold.stc.init_bold_stc_wf(metadata, name='bold_stc_wf')[source]

This workflow performs STC over the input BOLD image.

../_images/index-13.png

(Source code, png, svg, pdf)

Parameters

metadata : dict
BIDS metadata for BOLD file
name : str
Name of workflow (default: bold_stc_wf)

Inputs

bold_file
BOLD series NIfTI file
skip_vols
Number of non-steady-state volumes detected at beginning of bold_file

Outputs

stc_file
Slice-timing corrected BOLD series NIfTI file

Registration workflows

fmriprep.workflows.bold.registration.init_bold_reg_wf(freesurfer, use_bbr, bold2t1w_dof, mem_gb, omp_nthreads, name='bold_reg_wf', use_compression=True, use_fieldwarp=False)[source]

This workflow registers the reference BOLD image to T1-space, using a boundary-based registration (BBR) cost function.

If FreeSurfer-based preprocessing is enabled, the bbregister utility is used to align the BOLD images to the reconstructed subject, and the resulting transform is adjusted to target the T1 space. If FreeSurfer-based preprocessing is disabled, FSL FLIRT is used with the BBR cost function to directly target the T1 space.

../_images/index-14.png

(Source code, png, svg, pdf)

Parameters

freesurfer : bool
Enable FreeSurfer functional registration (bbregister)
use_bbr : bool or None
Enable/disable boundary-based registration refinement. If None, test BBR result for distortion before accepting.
bold2t1w_dof : 6, 9 or 12
Degrees-of-freedom for BOLD-T1w registration
mem_gb : float
Size of BOLD file in GB
omp_nthreads : int
Maximum number of threads an individual process may use
name : str
Name of workflow (default: bold_reg_wf)
use_compression : bool
Save registered BOLD series as .nii.gz
use_fieldwarp : bool
Include SDC warp in single-shot transform from BOLD to T1

Inputs

name_source
BOLD series NIfTI file Used to recover original information lost during processing
ref_bold_brain
Reference image to which BOLD series is aligned If fieldwarp == True, ref_bold_brain should be unwarped
ref_bold_mask
Skull-stripping mask of reference image
t1_preproc
Bias-corrected structural template image
t1_brain
Skull-stripped t1_preproc
t1_mask
Mask of the skull-stripped template image
t1_seg
Segmentation of preprocessed structural image, including gray-matter (GM), white-matter (WM) and cerebrospinal fluid (CSF)
bold_split
Individual 3D BOLD volumes, not motion corrected
hmc_xforms
List of affine transforms aligning each volume to ref_image in ITK format
subjects_dir
FreeSurfer SUBJECTS_DIR
subject_id
FreeSurfer subject ID
t1_2_fsnative_reverse_transform
LTA-style affine matrix translating from FreeSurfer-conformed subject space to T1w
fieldwarp
a DFM in ITK format

Outputs

itk_bold_to_t1
Affine transform from ref_bold_brain to T1 space (ITK format)
itk_t1_to_bold
Affine transform from T1 space to BOLD space (ITK format)
bold_t1
Motion-corrected BOLD series in T1 space
bold_mask_t1
BOLD mask in T1 space
out_report
Reportlet visualizing quality of registration
fallback
Boolean indicating whether BBR was rejected (mri_coreg registration returned)

Subworkflows

  • init_bbreg_wf()
  • init_fsl_bbr_wf()
fmriprep.workflows.bold.registration.init_bbreg_wf(use_bbr, bold2t1w_dof, omp_nthreads, name='bbreg_wf')[source]

This workflow uses FreeSurfer’s bbregister to register a BOLD image to a T1-weighted structural image.

It is a counterpart to init_fsl_bbr_wf(), which performs the same task using FSL’s FLIRT with a BBR cost function.

The use_bbr option permits a high degree of control over registration. If False, standard, affine coregistration will be performed using FreeSurfer’s mri_coreg tool. If True, bbregister will be seeded with the initial transform found by mri_coreg (equivalent to running bbregister --init-coreg). If None, after bbregister is run, the resulting affine transform will be compared to the initial transform found by mri_coreg. Excessive deviation will result in rejecting the BBR refinement and accepting the original, affine registration.

../_images/index-15.png

(Source code, png, svg, pdf)

Parameters

use_bbr : bool or None
Enable/disable boundary-based registration refinement. If None, test BBR result for distortion before accepting.
bold2t1w_dof : 6, 9 or 12
Degrees-of-freedom for BOLD-T1w registration
name : str, optional
Workflow name (default: bbreg_wf)

Inputs

in_file
Reference BOLD image to be registered
t1_2_fsnative_reverse_transform
FSL-style affine matrix translating from FreeSurfer T1.mgz to T1w
subjects_dir
FreeSurfer SUBJECTS_DIR
subject_id
FreeSurfer subject ID (must have folder in SUBJECTS_DIR)
t1_brain
Unused (see init_fsl_bbr_wf())
t1_seg
Unused (see init_fsl_bbr_wf())

Outputs

itk_bold_to_t1
Affine transform from ref_bold_brain to T1 space (ITK format)
itk_t1_to_bold
Affine transform from T1 space to BOLD space (ITK format)
out_report
Reportlet for assessing registration quality
fallback
Boolean indicating whether BBR was rejected (mri_coreg registration returned)
fmriprep.workflows.bold.registration.init_fsl_bbr_wf(use_bbr, bold2t1w_dof, name='fsl_bbr_wf')[source]

This workflow uses FSL FLIRT to register a BOLD image to a T1-weighted structural image, using a boundary-based registration (BBR) cost function.

It is a counterpart to init_bbreg_wf(), which performs the same task using FreeSurfer’s bbregister.

The use_bbr option permits a high degree of control over registration. If False, standard, rigid coregistration will be performed by FLIRT. If True, FLIRT-BBR will be seeded with the initial transform found by the rigid coregistration. If None, after FLIRT-BBR is run, the resulting affine transform will be compared to the initial transform found by FLIRT. Excessive deviation will result in rejecting the BBR refinement and accepting the original, affine registration.

(Source code)

Parameters

use_bbr : bool or None
Enable/disable boundary-based registration refinement. If None, test BBR result for distortion before accepting.
bold2t1w_dof : 6, 9 or 12
Degrees-of-freedom for BOLD-T1w registration
name : str, optional
Workflow name (default: fsl_bbr_wf)

Inputs

in_file
Reference BOLD image to be registered
t1_brain
Skull-stripped T1-weighted structural image
t1_seg
FAST segmentation of t1_brain
t1_2_fsnative_reverse_transform
Unused (see init_bbreg_wf())
subjects_dir
Unused (see init_bbreg_wf())
subject_id
Unused (see init_bbreg_wf())

Outputs

itk_bold_to_t1
Affine transform from ref_bold_brain to T1 space (ITK format)
itk_t1_to_bold
Affine transform from T1 space to BOLD space (ITK format)
out_report
Reportlet for assessing registration quality
fallback
Boolean indicating whether BBR was rejected (rigid FLIRT registration returned)

Resampling workflows

fmriprep.workflows.bold.resampling.init_bold_surf_wf(mem_gb, output_spaces, medial_surface_nan, name='bold_surf_wf')[source]

This workflow samples functional images to FreeSurfer surfaces

For each vertex, the cortical ribbon is sampled at six points (spaced 20% of thickness apart) and averaged.

Outputs are in GIFTI format.

../_images/index-17.png

(Source code, png, svg, pdf)

Parameters

output_spaces : list
List of output spaces functional images are to be resampled to Target spaces beginning with fs will be selected for resampling, such as fsaverage or related template spaces If the list contains fsnative, images will be resampled to the individual subject’s native surface
medial_surface_nan : bool
Replace medial wall values with NaNs on functional GIFTI files

Inputs

source_file
Motion-corrected BOLD series in T1 space
t1_preproc
Bias-corrected structural template image
subjects_dir
FreeSurfer SUBJECTS_DIR
subject_id
FreeSurfer subject ID
t1_2_fsnative_forward_transform
LTA-style affine matrix translating from T1w to FreeSurfer-conformed subject space

Outputs

surfaces
BOLD series, resampled to FreeSurfer surfaces
fmriprep.workflows.bold.resampling.init_bold_mni_trans_wf(template, mem_gb, omp_nthreads, name='bold_mni_trans_wf', output_grid_ref=None, use_compression=True, use_fieldwarp=False)[source]

This workflow samples functional images to the MNI template in a “single shot” from the original BOLD series.

../_images/index-18.png

(Source code, png, svg, pdf)

Parameters

template : str
Name of template targeted by ‘template’ output space
mem_gb : float
Size of BOLD file in GB
omp_nthreads : int
Maximum number of threads an individual process may use
name : str
Name of workflow (default: bold_mni_trans_wf)
output_grid_ref : str or None
Path of custom reference image for normalization
use_compression : bool
Save registered BOLD series as .nii.gz
use_fieldwarp : bool
Include SDC warp in single-shot transform from BOLD to MNI

Inputs

itk_bold_to_t1
Affine transform from ref_bold_brain to T1 space (ITK format)
t1_2_mni_forward_transform
ANTs-compatible affine-and-warp transform file
bold_split
Individual 3D volumes, not motion corrected
bold_mask
Skull-stripping mask of reference image
name_source
BOLD series NIfTI file Used to recover original information lost during processing
hmc_xforms
List of affine transforms aligning each volume to ref_image in ITK format
fieldwarp
a DFM in ITK format

Outputs

bold_mni
BOLD series, resampled to template space
bold_mask_mni
BOLD series mask in template space
fmriprep.workflows.bold.resampling.init_bold_preproc_trans_wf(mem_gb, omp_nthreads, name='bold_preproc_trans_wf', use_compression=True, use_fieldwarp=False)[source]

This workflow resamples the input fMRI in its native (original) space in a “single shot” from the original BOLD series.

../_images/index-19.png

(Source code, png, svg, pdf)

Parameters

mem_gb : float
Size of BOLD file in GB
omp_nthreads : int
Maximum number of threads an individual process may use
name : str
Name of workflow (default: bold_mni_trans_wf)
use_compression : bool
Save registered BOLD series as .nii.gz
use_fieldwarp : bool
Include SDC warp in single-shot transform from BOLD to MNI

Inputs

bold_split
Individual 3D volumes, not motion corrected
bold_mask
Skull-stripping mask of reference image
name_source
BOLD series NIfTI file Used to recover original information lost during processing
hmc_xforms
List of affine transforms aligning each volume to ref_image in ITK format
fieldwarp
a DFM in ITK format

Outputs

bold
BOLD series, resampled in native space, including all preprocessing
bold_mask
BOLD series mask calculated with the new time-series
bold_ref
BOLD reference image: an average-like 3D image of the time-series
bold_ref_brain
Same as bold_ref, but once the brain mask has been applied

Calculate BOLD confounds

fmriprep.workflows.bold.confounds.init_bold_confs_wf(mem_gb, use_aroma, ignore_aroma_err, metadata, name='bold_confs_wf')[source]

This workflow calculates confounds for a BOLD series, and aggregates them into a TSV file, for use as nuisance regressors in a GLM.

The following confounds are calculated, with column headings in parentheses:

  1. Region-wise average signal (CSF, WhiteMatter, GlobalSignal)
  2. DVARS - standard, nonstandard, and voxel-wise standard variants (stdDVARS, non-stdDVARS, vx-wisestdDVARS)
  3. Framewise displacement, based on MCFLIRT motion parameters (FramewiseDisplacement)
  4. Temporal CompCor (tCompCorXX)
  5. Anatomical CompCor (aCompCorXX)
  6. Cosine basis set for high-pass filtering w/ 0.008 Hz cut-off (CosineXX)
  7. Non-steady-state volumes (NonSteadyStateXX)
  8. Estimated head-motion parameters, in mm and rad (X, Y, Z, RotX, RotY, RotZ)
  9. ICA-AROMA-identified noise components, if enabled (AROMAAggrCompXX)

Prior to estimating aCompCor and tCompCor, non-steady-state volumes are censored and high-pass filtered using a DCT basis. The cosine basis, as well as one regressor per censored volume, are included for convenience.

../_images/index-20.png

(Source code, png, svg, pdf)

Parameters

mem_gb : float
Size of BOLD file in GB - please note that this size should be calculated after resamplings that may extend the FoV
use_aroma : bool
Perform ICA-AROMA on MNI-resampled functional series
ignore_aroma_err : bool
Do not fail on ICA-AROMA errors
metadata : dict
BIDS metadata for BOLD file

Inputs

bold
BOLD image, after the prescribed corrections (STC, HMC and SDC) when available.
bold_mask
BOLD series mask
movpar_file
SPM-formatted motion parameters file
t1_mask
Mask of the skull-stripped template image
t1_tpms
List of tissue probability maps in T1w space
t1_bold_xform
Affine matrix that maps the T1w space into alignment with the native BOLD space
bold_mni
BOLD image resampled in MNI space (only if use_aroma enabled)
bold_mask_mni
Brain mask corresponding to the BOLD image resampled in MNI space (only if use_aroma enabled)

Outputs

confounds_file
TSV of all aggregated confounds
confounds_list
List of calculated confounds for reporting
acompcor_report
Reportlet visualizing white-matter/CSF mask used for aCompCor
tcompcor_report
Reportlet visualizing ROI identified in tCompCor
ica_aroma_report
Reportlet visualizing MELODIC ICs, with ICA-AROMA signal/noise labels
aroma_noise_ics
CSV of noise components identified by ICA-AROMA
melodic_mix
FSL MELODIC mixing matrix
nonaggr_denoised_file
BOLD series with non-aggressive ICA-AROMA denoising applied

Subworkflows

fmriprep.workflows.bold.confounds.init_ica_aroma_wf(name='ica_aroma_wf', ignore_aroma_err=False)[source]

This workflow wraps ICA-AROMA to identify and remove motion-related independent components from a BOLD time series.

The following steps are performed:

  1. Smooth data using SUSAN
  2. Run MELODIC outside of ICA-AROMA to generate the report
  3. Run ICA-AROMA
  4. Aggregate identified motion components (aggressive) to TSV
  5. Return classified_motion_ICs and melodic_mix for user to complete
    non-aggressive denoising in T1w space

Additionally, non-aggressive denoising is performed on the BOLD series resampled into MNI space.

../_images/index-21.png

(Source code, png, svg, pdf)

Parameters

ignore_aroma_err : bool
Do not fail on ICA-AROMA errors

Inputs

bold_mni
BOLD series, resampled to template space
movpar_file
SPM-formatted motion parameters file
bold_mask_mni
BOLD series mask in template space

Outputs

aroma_confounds
TSV of confounds identified as noise by ICA-AROMA
aroma_noise_ics
CSV of noise components identified by ICA-AROMA
melodic_mix
FSL MELODIC mixing matrix
nonaggr_denoised_file
BOLD series with non-aggressive ICA-AROMA denoising applied
out_report
Reportlet visualizing MELODIC ICs, with ICA-AROMA signal/noise labels