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.
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.
(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
(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
(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.
(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.(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 arerecentered
to align with native T1w space.(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.
(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
init_bold_reference_wf()
init_bold_stc_wf()
init_bold_hmc_wf()
init_bold_reg_wf()
init_bold_confounds_wf()
init_bold_mni_trans_wf()
init_bold_preproc_trans_wf()
init_bold_surf_wf()
init_pepolar_unwarp_wf()
init_fmap_estimator_wf()
init_sdc_unwarp_wf()
init_nonlinear_sdc_wf()
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.
(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.
(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()
(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.
(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.
(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.(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. IfFalse
, standard, affine coregistration will be performed using FreeSurfer’smri_coreg
tool. IfTrue
,bbregister
will be seeded with the initial transform found bymri_coreg
(equivalent to runningbbregister --init-coreg
). IfNone
, afterbbregister
is run, the resulting affine transform will be compared to the initial transform found bymri_coreg
. Excessive deviation will result in rejecting the BBR refinement and accepting the original, affine registration.(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’sbbregister
.The
use_bbr
option permits a high degree of control over registration. IfFalse
, standard, rigid coregistration will be performed by FLIRT. IfTrue
, FLIRT-BBR will be seeded with the initial transform found by the rigid coregistration. IfNone
, 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.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.
(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 asfsaverage
or related template spaces If the list containsfsnative
, 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.
(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.
(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:
- Region-wise average signal (
CSF
,WhiteMatter
,GlobalSignal
) - DVARS - standard, nonstandard, and voxel-wise standard variants
(
stdDVARS
,non-stdDVARS
,vx-wisestdDVARS
) - Framewise displacement, based on MCFLIRT motion parameters
(
FramewiseDisplacement
) - Temporal CompCor (
tCompCorXX
) - Anatomical CompCor (
aCompCorXX
) - Cosine basis set for high-pass filtering w/ 0.008 Hz cut-off
(
CosineXX
) - Non-steady-state volumes (
NonSteadyStateXX
) - Estimated head-motion parameters, in mm and rad
(
X
,Y
,Z
,RotX
,RotY
,RotZ
) - 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.
(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
- Region-wise average signal (
-
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:
- Smooth data using SUSAN
- Run MELODIC outside of ICA-AROMA to generate the report
- Run ICA-AROMA
- Aggregate identified motion components (aggressive) to TSV
- 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.
(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