API¶
Workflows¶
fMRIprep base processing workflows¶
-
fmriprep.workflows.base.
init_fmriprep_wf
(subject_list, task_id, run_uuid, work_dir, output_dir, bids_dir, ignore, debug, low_mem, anat_only, longitudinal, t2s_coreg, omp_nthreads, skull_strip_template, skull_strip_fixed_seed, freesurfer, output_spaces, template, medial_surface_nan, cifti_output, hires, use_bbr, bold2t1w_dof, fmap_bspline, fmap_demean, use_syn, force_syn, use_aroma, ignore_aroma_err, aroma_melodic_dim, template_out_grid)[source]¶ This workflow organizes the execution of FMRIPREP, with a sub-workflow for each subject.
If FreeSurfer’s recon-all is to be run, a FreeSurfer derivatives folder is created and populated with any needed template subjects.
(Source code, png, svg, pdf)
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
- 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
- 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
- t2s_coreg : bool
- Use multiple BOLD echos to create T2*-map for T2*-driven coregistration
- 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’)
- skull_strip_fixed_seed : bool
- Do not use a random seed for skull-stripping - will ensure run-to-run replicability when used with –omp-nthreads 1
- 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
- cifti_output : bool
- Generate bold CIFTI file in output spaces
- 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
- template_out_grid : str
- Keyword (‘native’, ‘1mm’ or ‘2mm’) or path of custom reference image for normalization
-
fmriprep.workflows.base.
init_single_subject_wf
(subject_id, task_id, name, reportlets_dir, output_dir, bids_dir, ignore, debug, low_mem, anat_only, longitudinal, t2s_coreg, omp_nthreads, skull_strip_template, skull_strip_fixed_seed, freesurfer, output_spaces, template, medial_surface_nan, cifti_output, hires, use_bbr, bold2t1w_dof, fmap_bspline, fmap_demean, use_syn, force_syn, template_out_grid, use_aroma, aroma_melodic_dim, 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
- t2s_coreg : bool
- Use multiple BOLDS echos to create T2*-map for T2*-driven coregistration
- 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’)
- skull_strip_fixed_seed : bool
- Do not use a random seed for skull-stripping - will ensure run-to-run replicability when used with –omp-nthreads 1
- 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
- cifti_output : bool
- Generate bold CIFTI file in output spaces
- 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
- template_out_grid : str
- Keyword (‘native’, ‘1mm’ or ‘2mm’) or 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, num_t1w, skull_strip_fixed_seed=False, 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)
- skull_strip_fixed_seed : bool
- Do not use a random seed for skull-stripping - will ensure
run-to-run replicability when used with –omp-nthreads 1 (default:
False
)
Inputs
- t1w
- List of T1-weighted structural images
- t2w
- List of T2-weighted structural images
- flair
- List of FLAIR 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, skull_strip_fixed_seed=False, 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
- skull_strip_fixed_seed : bool
- Do not use a random seed for skull-stripping - will ensure
run-to-run replicability when used with –omp-nthreads 1 (default:
False
)
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. 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 substract 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.
(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
- 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_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
- 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 image
- use_FLAIR
- Refine pial surface using FLAIR image
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, t2s_coreg, bold2t1w_dof, reportlets_dir, output_spaces, template, output_dir, omp_nthreads, fmap_bspline, fmap_demean, use_syn, force_syn, use_aroma, ignore_aroma_err, aroma_melodic_dim, medial_surface_nan, cifti_output, debug, low_mem, template_out_grid, layout=None, num_bold=1)[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. - t2s_coreg : bool
- Use multiple BOLD echos to create T2*-map for T2*-driven coregistration
- 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
- cifti_output : bool
- Generate bold CIFTI file in output spaces
- debug : bool
- Enable debugging outputs
- low_mem : bool
- Write uncompressed .nii files in some cases to reduce memory usage
- template_out_grid : str
- Keyword (‘native’, ‘1mm’ or ‘2mm’) or path of custom reference image for normalization
- layout : BIDSLayout
- BIDSLayout structure to enable metadata retrieval
- num_bold : int
- Total number of BOLD files that have been set for preprocessing (default is 1)
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
- bold_cifti
- BOLD CIFTI image
- cifti_variant
- combination of target spaces for bold_cifti
Subworkflows
init_bold_reference_wf()
init_bold_stc_wf()
init_bold_hmc_wf()
init_bold_t2s_wf()
init_bold_t1_trans_wf()
init_bold_reg_wf()
init_bold_confounds_wf()
init_ica_aroma_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', gen_report=False, enhance_t2=False)[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
) - gen_report : bool
- Whether a mask report node should be appended in the end
- enhance_t2 : bool
- Perform logarithmic transform of input BOLD image to improve contrast before calculating the preliminary mask
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
- 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, enhance_t2=False)[source]¶ This workflow takes in a BOLD fMRI average/summary (e.g. a reference image averaging non-steady-state timepoints), and sharpens the histogram with the application of the N4 algorithm for removing the INU bias field and calculates a signal mask.
Steps of this workflow are:
- Calculate a conservative mask using Nilearn’s
create_epi_mask
. - Run ANTs’
N4BiasFieldCorrection
on the input BOLD average, using the mask generated in 1) instead of the internal Otsu thresholding. - Calculate a loose mask using FSL’s
bet
, with one mathematical morphology dilation of one iteration and a sphere of 6mm as structuring element. - Mask the INU-corrected image
with the latest mask calculated in 3), then use AFNI’s
3dUnifize
to standardize the T2* contrast distribution. - Calculate a mask using AFNI’s
3dAutomask
after the contrast enhancement of 4). - Calculate a final mask as the intersection of 3) and 5).
- Apply final mask on the enhanced reference.
(Source code, png, svg, pdf)
- Parameters
- name : str
- Name of workflow (default:
enhance_and_skullstrip_bold_wf
) - omp_nthreads : int
- number of threads available to parallel nodes
- enhance_t2 : bool
- perform logarithmic transform of input BOLD image to improve contrast before calculating the preliminary mask
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
- Calculate a conservative mask using Nilearn’s
-
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 estimates the motion parameters to perform 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
- 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
Generate T2* map from multi-echo BOLD images¶
-
fmriprep.workflows.bold.t2s.
init_bold_t2s_wf
(bold_echos, echo_times, mem_gb, omp_nthreads, name='bold_t2s_wf', use_compression=True, use_fieldwarp=False)[source]¶ This workflow performs HMC on individual echo_files, uses T2SMap to generate a T2* image for coregistration instead of mean BOLD EPI.
(Source code, png, svg, pdf)
Parameters
- bold_echos
- list of ME-BOLD files
- echo_times
- list of TEs associated with each echo
- 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_t2s_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
- name_source
- (one echo of) the original BOLD series NIfTI file Used to recover original information lost during processing
- hmc_xforms
- ITKTransform file aligning each volume to
ref_image
Outputs
- t2s_map
- the T2* map for the EPI run
- oc_mask
- the skull-stripped optimal combination mask
Registration workflows¶
-
fmriprep.workflows.bold.registration.
init_bold_reg_wf
(freesurfer, use_bbr, bold2t1w_dof, mem_gb, omp_nthreads, use_compression=True, write_report=True, name='bold_reg_wf')[source]¶ Calculates the registration between a reference BOLD image and 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
- write_report : bool
- Whether a reportlet should be stored
Inputs
- ref_bold_brain
- Reference image to which BOLD series is aligned
If
fieldwarp == True
,ref_bold_brain
should be unwarped - t1_brain
- Skull-stripped
t1_preproc
- t1_seg
- Segmentation of preprocessed structural image, including gray-matter (GM), white-matter (WM) and cerebrospinal fluid (CSF)
- 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
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)
- fallback
- Boolean indicating whether BBR was rejected (mri_coreg registration returned)
Subworkflows
init_bbreg_wf()
init_fsl_bbr_wf()
-
fmriprep.workflows.bold.registration.
init_bold_t1_trans_wf
(freesurfer, mem_gb, omp_nthreads, use_fieldwarp=False, use_compression=True, name='bold_t1_trans_wf')[source]¶ This workflow registers the reference BOLD image to T1-space, using a boundary-based registration (BBR) cost function.
(Source code, png, svg, pdf)
Parameters
- freesurfer : bool
- Enable FreeSurfer functional registration (bbregister)
- use_fieldwarp : bool
- Include SDC warp in single-shot transform from BOLD to T1
- mem_gb : float
- Size of BOLD file in GB
- omp_nthreads : int
- Maximum number of threads an individual process may use
- use_compression : bool
- Save registered BOLD series as
.nii.gz
- name : str
- Name of workflow (default:
bold_reg_wf
)
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_brain
- Skull-stripped bias-corrected structural template image
- t1_mask
- Mask of the skull-stripped template image
- t1_aseg
- FreeSurfer’s
aseg.mgz
atlas projected into the T1w reference (only ifrecon-all
was run). - t1_aparc
- FreeSurfer’s
aparc+aseg.mgz
atlas projected into the T1w reference (only ifrecon-all
was run). - bold_split
- Individual 3D BOLD volumes, not motion corrected
- hmc_xforms
- List of affine transforms aligning each volume to
ref_image
in ITK format - itk_bold_to_t1
- Affine transform from
ref_bold_brain
to T1 space (ITK format) - fieldwarp
- a DFM in ITK format
Outputs
- bold_t1
- Motion-corrected BOLD series in T1 space
- bold_mask_t1
- BOLD mask in T1 space
- bold_aseg_t1
- FreeSurfer’s
aseg.mgz
atlas, in T1w-space at the BOLD resolution (only ifrecon-all
was run). - bold_aparc_t1
- FreeSurfer’s
aparc+aseg.mgz
atlas, in T1w-space at the BOLD resolution (only ifrecon-all
was run).
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', template_out_grid='2mm', 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
) - template_out_grid : str
- Keyword (‘native’, ‘1mm’ or ‘2mm’) or 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, split_file=False, interpolation='LanczosWindowedSinc')[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
- split_file : bool
- Whether the input file should be splitted (it is a 4D file)
or it is a list of 3D files (default
False
, do not split) - interpolation : str
- Interpolation type to be used by ANTs’
applyTransforms
(default'LanczosWindowedSinc'
)
Inputs
- bold_file
- 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, 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
)
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
- metadata : dict
- BIDS metadata for BOLD file
- name : str
- Name of workflow (default:
bold_confs_wf
)
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
Outputs
- confounds_file
- TSV of all aggregated confounds
- rois_report
- Reportlet visualizing white-matter/CSF mask used for aCompCor, the ROI for tCompCor and the BOLD brain mask.
- Region-wise average signal (
-
fmriprep.workflows.bold.confounds.
init_ica_aroma_wf
(template, metadata, mem_gb, omp_nthreads, name='ica_aroma_wf', susan_fwhm=6.0, ignore_aroma_err=False, aroma_melodic_dim=None, use_fieldwarp=True)[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 FSL susan, with a kernel width FWHM=6.0mm.
- Run FSL melodic outside of ICA-AROMA to generate the report
- Run ICA-AROMA
- Aggregate identified motion components (aggressive) to TSV
- Return
classified_motion_ICs
andmelodic_mix
for user to complete non-aggressive denoising in T1w space - Calculate ICA-AROMA-identified noise components
(columns named
AROMAAggrCompXX
)
Additionally, non-aggressive denoising is performed on the BOLD series resampled into MNI space.
There is a current discussion on whether other confounds should be extracted before or after denoising here.
(Source code, png, svg, pdf)
Parameters
- template : str
- Spatial normalization template used as target when that
registration step was previously calculated with
init_bold_reg_wf()
. The template must be one of the MNI templates (fMRIPrep usesMNI152NLin2009cAsym
by default). - metadata : dict
- BIDS metadata for BOLD file
- 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
) - susan_fwhm : float
- Kernel width (FWHM in mm) for the smoothing step with
FSL
susan
(default: 6.0mm) - use_fieldwarp : bool
- Include SDC warp in single-shot transform from BOLD to MNI
- ignore_aroma_err : bool
- Do not fail on ICA-AROMA errors
- aroma_melodic_dim: int or None
- Set the dimensionality of the Melodic ICA decomposition If None, MELODIC automatically estimates dimensionality.
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
Fieldmap estimation and unwarping workflows¶
Automatic selection of the appropriate SDC method¶
If the dataset metadata indicate tha more than one field map acquisition is
IntendedFor
(see BIDS Specification section 8.9) the following priority will
be used:
Table of behavior (fieldmap use-cases):
Fieldmaps found | use_syn |
force_syn |
Action |
---|---|---|---|
True | True | Fieldmaps + SyN | |
True | False | Fieldmaps | |
False | True | SyN | |
False | True | False | SyN |
False | False | False | HMC only |
-
fmriprep.workflows.fieldmap.base.
init_sdc_wf
(fmaps, bold_meta, omp_nthreads=1, debug=False, fmap_bspline=False, fmap_demean=True)[source]¶ This workflow implements the heuristics to choose a SDC strategy. When no field map information is present within the BIDS inputs, the EXPERIMENTAL “fieldmap-less SyN” can be performed, using the
--use-syn
argument. When--force-syn
is specified, then the “fieldmap-less SyN” is always executed and reported despite of other fieldmaps available with higher priority. In the latter case (some sort of fieldmap(s) is available and--force-syn
is requested), then the SDC method applied is that with the highest priority.(Source code, png, svg, pdf)
Parameters
- fmaps : list of pybids dicts
- A list of dictionaries with the available fieldmaps
(and their metadata using the key
'metadata'
for the case of epi fieldmaps) - bold_meta : dict
- BIDS metadata dictionary corresponding to the BOLD run
- 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
- debug : bool
- Enable debugging outputs
- Inputs
- bold_ref
- A BOLD reference calculated at a previous stage
- bold_ref_brain
- Same as above, but brain-masked
- bold_mask
- Brain mask for the BOLD run
- t1_brain
- T1w image, brain-masked, for the fieldmap-less SyN method
- t1_2_mni_reverse_transform
- MNI-to-T1w transform to map prior knowledge to the T1w fo the fieldmap-less SyN method
- template : str
- Name of template targeted by
template
output space
- Outputs
- bold_ref
- An unwarped BOLD reference
- bold_mask
- The corresponding new mask after unwarping
- bold_ref_brain
- Brain-extracted, unwarped BOLD reference
- out_warp
- The deformation field to unwarp the susceptibility distortions
- syn_bold_ref
- If
--force-syn
, an unwarped BOLD reference with this method (for reporting purposes)
Direct B0 mapping sequences¶
When the fieldmap is directly measured with a prescribed sequence (such as SE), we only need to calculate the corresponding B-Spline coefficients to adapt the fieldmap to the TOPUP tool. This procedure is described with more detail here.
This corresponds to the section 8.9.3 –fieldmap image (and one magnitude image)– of the BIDS specification.
-
fmriprep.workflows.fieldmap.fmap.
init_fmap_wf
(omp_nthreads, fmap_bspline, name='fmap_wf')[source]¶ Fieldmap workflow - when we have a sequence that directly measures the fieldmap we just need to mask it (using the corresponding magnitude image) to remove the noise in the surrounding air region, and ensure that units are Hz.
(Source code, png, svg, pdf)
Phase-difference B0 estimation¶
The field inhomogeneity inside the scanner (fieldmap) is proportional to the phase drift between two subsequent GRE sequence.
Fieldmap preprocessing workflow for fieldmap data structure 8.9.1 in BIDS 1.0.0: one phase diff and at least one magnitude image
-
fmriprep.workflows.fieldmap.phdiff.
init_phdiff_wf
(omp_nthreads, name='phdiff_wf')[source]¶ Estimates the fieldmap using a phase-difference image and one or more magnitude images corresponding to two or more GRE acquisitions. The original code was taken from nipype.
(Source code, png, svg, pdf)
Outputs:
outputnode.fmap_ref - The average magnitude image, skull-stripped outputnode.fmap_mask - The brain mask applied to the fieldmap outputnode.fmap - The estimated fieldmap in Hz
Phase Encoding POLARity (PEPOLAR) techniques¶
-
fmriprep.workflows.fieldmap.pepolar.
init_pepolar_unwarp_wf
(bold_meta, epi_fmaps, omp_nthreads=1, name='pepolar_unwarp_wf')[source]¶ This workflow takes in a set of EPI files with opposite phase encoding direction than the target file and calculates a displacements field (in other words, an ANTs-compatible warp file).
This procedure works if there is only one ‘_epi’ file is present (as long as it has the opposite phase encoding direction to the target file). The target file will be used to estimate the field distortion. However, if there is another ‘_epi’ file present with a matching phase encoding direction to the target it will be used instead.
Currently, different phase encoding dimension in the target file and the ‘_epi’ file(s) (for example ‘i’ and ‘j’) is not supported.
The warp field correcting for the distortions is estimated using AFNI’s 3dQwarp, with displacement estimation limited to the target file phase encoding direction.
It also calculates a new mask for the input dataset that takes into account the distortions.
(Source code, png, svg, pdf)
Inputs
- in_reference
- the reference image
- in_reference_brain
- the reference image skullstripped
- in_mask
- a brain mask corresponding to
in_reference
Outputs
- out_reference
- the
in_reference
after unwarping - out_reference_brain
- the
in_reference
after unwarping and skullstripping - out_warp
- the corresponding DFM compatible with ANTs
- out_mask
- mask of the unwarped input file
-
fmriprep.workflows.fieldmap.pepolar.
init_prepare_epi_wf
(omp_nthreads, name='prepare_epi_wf')[source]¶ This workflow takes in a set of EPI files with with the same phase encoding direction and returns a single 3D volume ready to be used in field distortion estimation.
The procedure involves: estimating a robust template using FreeSurfer’s ‘mri_robust_template’, bias field correction using ANTs N4BiasFieldCorrection and AFNI 3dUnifize, skullstripping using FSL BET and AFNI 3dAutomask, and rigid coregistration to the reference using ANTs.
(Source code, png, svg, pdf)
Inputs
- fmaps
- list of 3D or 4D NIfTI images
- ref_brain
- coregistration reference (skullstripped and bias field corrected)
Outputs
- out_file
- single 3D NIfTI file
Fieldmap-less estimation (experimental)¶
In the absence of direct measurements of fieldmap data, we provide an (experimental)
option to estimate the susceptibility distortion based on the ANTs symmetric
normalization (SyN) technique.
This feature may be enabled, using the --use-syn-sdc
flag, and will only be
applied if fieldmaps are unavailable.
During the evaluation phase, the --force-syn
flag will cause this estimation to
be performed in addition to fieldmap-based estimation, to permit the direct
comparison of the results of each technique.
Note that, even if --force-syn
is given, the functional outputs of FMRIPREP will
be corrected using the fieldmap-based estimates.
Feedback will be enthusiastically received.
-
fmriprep.workflows.fieldmap.syn.
init_syn_sdc_wf
(omp_nthreads, bold_pe=None, atlas_threshold=3, name='syn_sdc_wf')[source]¶ This workflow takes a skull-stripped T1w image and reference BOLD image and estimates a susceptibility distortion correction warp, using ANTs symmetric normalization (SyN) and the average fieldmap atlas described in [Treiber2016].
SyN deformation is restricted to the phase-encoding (PE) direction. If no PE direction is specified, anterior-posterior PE is assumed.
SyN deformation is also restricted to regions that are expected to have a >3mm (approximately 1 voxel) warp, based on the fieldmap atlas.
This technique is a variation on those developed in [Huntenburg2014] and [Wang2017].
(Source code, png, svg, pdf)
Inputs
- bold_ref
- reference image
- bold_ref_brain
- skull-stripped reference image
- template : str
- Name of template targeted by
template
output space - t1_brain
- skull-stripped, bias-corrected structural image
- t1_2_mni_reverse_transform
- inverse registration transform of T1w image to MNI template
Outputs
- out_reference
- the
bold_ref
image after unwarping - out_reference_brain
- the
bold_ref_brain
image after unwarping - out_warp
- the corresponding DFM compatible with ANTs
- out_mask
- mask of the unwarped input file
Unwarping¶
Abbreviations
- fmap
- fieldmap
- VSM
- voxel-shift map – a 3D nifti where displacements are in pixels (not mm)
- DFM
- displacements field map – a nifti warp file compatible with ANTs (mm)
-
fmriprep.workflows.fieldmap.unwarp.
init_fmap_unwarp_report_wf
(name='fmap_unwarp_report_wf', suffix='variant-hmcsdc_preproc')[source]¶ This workflow generates and saves a reportlet showing the effect of fieldmap unwarping a BOLD image.
(Source code, png, svg, pdf)
Parameters
- name : str, optional
- Workflow name (default: fmap_unwarp_report_wf)
- suffix : str, optional
- Suffix to be appended to this reportlet
Inputs
- in_pre
- Reference image, before unwarping
- in_post
- Reference image, after unwarping
- in_seg
- Segmentation of preprocessed structural image, including gray-matter (GM), white-matter (WM) and cerebrospinal fluid (CSF)
- in_xfm
- Affine transform from T1 space to BOLD space (ITK format)
-
fmriprep.workflows.fieldmap.unwarp.
init_sdc_unwarp_wf
(omp_nthreads, fmap_demean, debug, name='sdc_unwarp_wf')[source]¶ This workflow takes in a displacements fieldmap and calculates the corresponding displacements field (in other words, an ANTs-compatible warp file).
It also calculates a new mask for the input dataset that takes into account the distortions. The mask is restricted to the field of view of the fieldmap since outside of it corrections could not be performed.
(Source code, png, svg, pdf)
Inputs
- in_reference
- the reference image
- in_reference_brain
- the reference image (skull-stripped)
- in_mask
- a brain mask corresponding to
in_reference
- metadata
- metadata associated to the
in_reference
EPI input - fmap
- the fieldmap in Hz
- fmap_ref
- the reference (anatomical) image corresponding to
fmap
- fmap_mask
- a brain mask corresponding to
fmap
Outputs
- out_reference
- the
in_reference
after unwarping - out_reference_brain
- the
in_reference
after unwarping and skullstripping - out_warp
- the corresponding DFM compatible with ANTs
- out_jacobian
- the jacobian of the field (for drop-out alleviation)
- out_mask
- mask of the unwarped input file