Developers - API¶
Workflows¶
fMRIPrep base processing workflows¶
-
fmriprep.workflows.base.
init_fmriprep_wf
(anat_only, aroma_melodic_dim, bold2t1w_dof, cifti_output, debug, dummy_scans, echo_idx, err_on_aroma_warn, fmap_bspline, fmap_demean, force_syn, freesurfer, fs_subjects_dir, hires, ignore, layout, longitudinal, low_mem, medial_surface_nan, omp_nthreads, output_dir, regressors_all_comps, regressors_dvars_th, regressors_fd_th, run_uuid, skull_strip_fixed_seed, skull_strip_template, spaces, subject_list, t2s_coreg, task_id, use_aroma, use_bbr, use_syn, work_dir, bids_filters)[source]¶ Build fMRIPrep’s pipeline.
This workflow organizes the execution of FMRIPREP, with a sub-workflow for each subject.
If FreeSurfer’s
recon-all
is to be run, a corresponding folder is created and populated with any needed template subjects under the derivatives folder.- Workflow Graph
(Source code, png, svg, pdf)
- Parameters
anat_only (
bool
) – Disable functional workflowsbold2t1w_dof (6, 9 or 12) – Degrees-of-freedom for BOLD-T1w registration
cifti_output (
bool
) – Generate bold CIFTI file in output spacesdebug (
bool
) – Enable debugging outputsdummy_scans (
int
or None) – Number of volumes to consider as non steady stateecho_idx (
int
or None) – Index of echo to preprocess in multiecho BOLD series, orNone
to preprocess allerr_on_aroma_warn (
bool
) – Do not fail on ICA-AROMA errorsfmap_bspline (
bool
) – Experimental: Fit B-Spline field using least-squaresfmap_demean (
bool
) – Demean voxel-shift map during unwarpforce_syn (
bool
) – Temporary: Always run SyN-based SDCfreesurfer (
bool
) – Enable FreeSurfer surface reconstruction (may increase runtime)hires (
bool
) – Enable sub-millimeter preprocessing in FreeSurferignore (
list
) – Preprocessing steps to skip (may include “slicetiming”, “fieldmaps”)layout (
BIDSLayout
) – BIDS dataset layoutlongitudinal (
bool
) – Treat multiple sessions as longitudinal (may increase runtime) See sub-workflows for specific differenceslow_mem (
bool
) – Write uncompressed .nii files in some cases to reduce memory usagemedial_surface_nan (
bool
) – Replace medial wall values with NaNs on functional GIFTI filesomp_nthreads (
int
) – Maximum number of threads an individual process may useoutput_dir (
str
) – Directory in which to save derivativesregressors_all_comps (
bool
) – Return all CompCor component time series instead of the top fractionregressors_dvars_th (
float
) – Criterion for flagging DVARS outliersregressors_fd_th (
float
) – Criterion for flagging framewise displacement outliersrun_uuid (
str
) – Unique identifier for execution instanceskull_strip_template (tuple) – Name of target template for brain extraction with ANTs’
antsBrainExtraction
, and corresponding dictionary of output-space modifiers.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 1spaces (
SpatialReferences
) – A container for storing, organizing, and parsing spatial normalizations. Composed ofReference
objects representing spatial references. EachReference
contains a space, which is a string of either TemplateFlow template IDs (e.g.,MNI152Lin
,MNI152NLin6Asym
,MNIPediatricAsym
), nonstandard references (e.g.,T1w
oranat
,sbref
,run
, etc.), or a custom template located in the TemplateFlow root directory. EachReference
may also contain a spec, which is a dictionary with template specifications (e.g., a specification of{'resolution': 2}
would lead to resampling on a 2mm resolution of the space).subject_list (
list
) – List of subject labelst2s_coreg (
bool
) – For multi-echo EPI, use the calculated T2*-map for T2*-driven coregistrationtask_id (
str
or None) – Task ID of BOLD series to preprocess, orNone
to preprocess alluse_aroma (
bool
) – Perform ICA-AROMA on MNI-resampled functional seriesuse_bbr (
bool
or None) – Enable/disable boundary-based registration refinement. IfNone
, test BBR result for distortion before accepting.use_syn (
bool
) – Experimental: Enable ANTs SyN-based susceptibility distortion correction (SDC). If fieldmaps are present and enabled, this is not run, by default.work_dir (
str
) – Directory in which to store workflow execution state and temporary filesbids_filters (
dict
) – Provides finer specification of the pipeline input files using pybids entities filters. A dict with the following structure {<suffix>:{<entity>:<filter>,…},…}
-
fmriprep.workflows.base.
init_single_subject_wf
(anat_only, aroma_melodic_dim, bold2t1w_dof, cifti_output, debug, dummy_scans, echo_idx, err_on_aroma_warn, fmap_bspline, fmap_demean, force_syn, freesurfer, hires, ignore, layout, longitudinal, low_mem, medial_surface_nan, name, omp_nthreads, output_dir, reportlets_dir, regressors_all_comps, regressors_dvars_th, regressors_fd_th, skull_strip_fixed_seed, skull_strip_template, spaces, subject_id, t2s_coreg, task_id, use_aroma, use_bbr, use_syn, bids_filters)[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.
- Workflow Graph
(Source code, png, svg, pdf)
- Parameters
anat_only (
bool
) – Disable functional workflowsaroma_melodic_dim (
int
) – Maximum number of components identified by MELODIC within ICA-AROMA (default is -200, i.e., no limitation).bold2t1w_dof (6, 9 or 12) – Degrees-of-freedom for BOLD-T1w registration
cifti_output (
bool
) – Generate bold CIFTI file in output spacesdebug (
bool
) – Enable debugging outputsdummy_scans (
int
or None) – Number of volumes to consider as non steady stateecho_idx (
int
or None) – Index of echo to preprocess in multiecho BOLD series, orNone
to preprocess allerr_on_aroma_warn (
bool
) – Do not fail on ICA-AROMA errorsfmap_bspline (
bool
) – Experimental: Fit B-Spline field using least-squaresfmap_demean (
bool
) – Demean voxel-shift map during unwarpforce_syn (
bool
) – Temporary: Always run SyN-based SDCfreesurfer (
bool
) – Enable FreeSurfer surface reconstruction (may increase runtime)hires (
bool
) – Enable sub-millimeter preprocessing in FreeSurferignore (
list
) – Preprocessing steps to skip (may include “slicetiming”, “fieldmaps”)layout (
BIDSLayout
) – BIDS dataset layoutlongitudinal (
bool
) – Treat multiple sessions as longitudinal (may increase runtime) See sub-workflows for specific differenceslow_mem (
bool
) – Write uncompressed .nii files in some cases to reduce memory usagemedial_surface_nan (
bool
) – Replace medial wall values with NaNs on functional GIFTI filesname (
str
) – Name of workflowomp_nthreads (
int
) – Maximum number of threads an individual process may useoutput_dir (
str
) – Directory in which to save derivativesreportlets_dir (
str
) – Directory in which to save reportletsregressors_all_comps (
bool
) – Return all CompCor component time series instead of the top fractionregressors_dvars_th (
float
) – Criterion for flagging DVARS outliersregressors_fd_th (
float
) – Criterion for flagging framewise displacement outliersskull_strip_fixed_seed (
bool
) – Do not use a random seed for skull-stripping - will ensure run-to-run replicability when used with –omp-nthreads 1skull_strip_template (tuple) – Name of target template for brain extraction with ANTs’
antsBrainExtraction
, and corresponding dictionary of output-space modifiers.subject_id (
str
) – List of subject labelst2s_coreg (
bool
) – For multi-echo EPI, use the calculated T2*-map for T2*-driven coregistrationspaces (
SpatialReferences
) – A container for storing, organizing, and parsing spatial normalizations. Composed ofReference
objects representing spatial references. EachReference
contains a space, which is a string of either TemplateFlow template IDs (e.g.,MNI152Lin
,MNI152NLin6Asym
,MNIPediatricAsym
), nonstandard references (e.g.,T1w
oranat
,sbref
,run
, etc.), or a custom template located in the TemplateFlow root directory. EachReference
may also contain a spec, which is a dictionary with template specifications (e.g., a specification of{'resolution': 2}
would lead to resampling on a 2mm resolution of the space).task_id (
str
or None) – Task ID of BOLD series to preprocess, orNone
to preprocess alluse_aroma (
bool
) – Perform ICA-AROMA on MNI-resampled functional seriesuse_bbr (
bool
or None) – Enable/disable boundary-based registration refinement. IfNone
, test BBR result for distortion before accepting.use_syn (
bool
) – Experimental: Enable ANTs SyN-based susceptibility distortion correction (SDC). If fieldmaps are present and enabled, this is not run, by default.bids_filters (
dict
) – Provides finer specification of the pipeline input files using pybids entities filters. A dict with the following structure {<suffix>:{<entity>:<filter>,…},…}
- Inputs
subjects_dir (
str
) – FreeSurfer’s$SUBJECTS_DIR
.
Pre-processing fMRI - BOLD signal workflows¶
Orchestrating the BOLD-preprocessing workflow¶
-
fmriprep.workflows.bold.base.
init_func_preproc_wf
(aroma_melodic_dim, bold2t1w_dof, bold_file, cifti_output, debug, dummy_scans, err_on_aroma_warn, fmap_bspline, fmap_demean, force_syn, freesurfer, ignore, low_mem, medial_surface_nan, omp_nthreads, output_dir, regressors_all_comps, regressors_dvars_th, regressors_fd_th, reportlets_dir, spaces, t2s_coreg, use_aroma, use_bbr, use_syn, layout=None, num_bold=1)[source]¶ This workflow controls the functional preprocessing stages of fMRIPrep.
- Workflow Graph
(Source code, png, svg, pdf)
- Parameters
aroma_melodic_dim (
int
) – Maximum number of components identified by MELODIC within ICA-AROMA (default is -200, ie. no limitation).bold2t1w_dof (6, 9 or 12) – Degrees-of-freedom for BOLD-T1w registration
bold_file (
str
) – BOLD series NIfTI filecifti_output (
bool
) – Generate bold CIFTI file in output spacesdebug (
bool
) – Enable debugging outputsdummy_scans (
int
or None) – Number of volumes to consider as non steady stateerr_on_aroma_warn (
bool
) – Do not crash on ICA-AROMA errorsfmap_bspline (
bool
) – Experimental: Fit B-Spline field using least-squaresfmap_demean (
bool
) – Demean voxel-shift map during unwarpforce_syn (
bool
) – Temporary: Always run SyN-based SDCfreesurfer (
bool
) – Enable FreeSurfer functional registration (bbregister) and resampling BOLD series to FreeSurfer surface meshes.ignore (
list
) – Preprocessing steps to skip (may include “slicetiming”, “fieldmaps”)low_mem (
bool
) – Write uncompressed .nii files in some cases to reduce memory usagemedial_surface_nan (
bool
) – Replace medial wall values with NaNs on functional GIFTI filesomp_nthreads (
int
) – Maximum number of threads an individual process may useoutput_dir (
str
) – Directory in which to save derivativesregressors_all_comps (
bool
) – Return all CompCor component time series instead of the top fractionregressors_dvars_th (
float
) – Criterion for flagging DVARS outliersregressors_fd_th (
float
) – Criterion for flagging framewise displacement outliersreportlets_dir (
str
) – Absolute path of a directory in which reportlets will be temporarily storedspaces (
SpatialReferences
) – A container for storing, organizing, and parsing spatial normalizations. Composed ofReference
objects representing spatial references. EachReference
contains a space, which is a string of either TemplateFlow template IDs (e.g.,MNI152Lin
,MNI152NLin6Asym
,MNIPediatricAsym
), nonstandard references (e.g.,T1w
oranat
,sbref
,run
, etc.), or a custom template located in the TemplateFlow root directory. EachReference
may also contain a spec, which is a dictionary with template specifications (e.g., a specification of{'resolution': 2}
would lead to resampling on a 2mm resolution of the space).t2s_coreg (
bool
) – For multiecho EPI, use the calculated T2*-map for T2*-driven coregistrationuse_aroma (
bool
) – Perform ICA-AROMA on MNI-resampled functional seriesuse_bbr (
bool
or None) – Enable/disable boundary-based registration refinement. IfNone
, test BBR result for distortion before accepting. When usingt2s_coreg
, BBR will be enabled by default unless explicitly specified otherwise.use_syn (
bool
) – Experimental: Enable ANTs SyN-based susceptibility distortion correction (SDC). If fieldmaps are present and enabled, this is not run, by default.layout (
BIDSLayout
) – BIDSLayout structure to enable metadata retrievalnum_bold (
int
) – Total number of BOLD files that have been set for preprocessing (default is 1)
- Inputs
bold_file – BOLD series NIfTI file
t1w_preproc – Bias-corrected structural template image
t1w_brain – Skull-stripped
t1w_preproc
t1w_mask – Mask of the skull-stripped template image
t1w_dseg – Segmentation of preprocessed structural image, including gray-matter (GM), white-matter (WM) and cerebrospinal fluid (CSF)
t1w_asec – Segmentation of structural image, done with FreeSurfer.
t1w_aparc – Parcellation of structural image, done with FreeSurfer.
t1w_tpms – List of tissue probability maps in T1w space
template – Name of the template (parametric)
anat2std_xfm – ANTs-compatible affine-and-warp transform file (parametric)
std2anat_xfm – ANTs-compatible affine-and-warp transform file (inverse) (parametric)
joint_template – List of templates to target
joint_anat2std_xfm – List of transform files, collated with templates
joint_std2anat_xfm – List of inverse transform files, collated with templates
subjects_dir – FreeSurfer SUBJECTS_DIR
subject_id – FreeSurfer subject ID
t1w2fsnative_xfm – LTA-style affine matrix translating from T1w to FreeSurfer-conformed subject space
fsnative2t1w_xfm – LTA-style affine matrix translating from FreeSurfer-conformed subject space to T1w
- Outputs
bold_t1 – BOLD series, resampled to T1w space
bold_mask_t1 – BOLD series mask in T1w space
bold_std – BOLD series, resampled to template space
bold_mask_std – 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
See also
init_bold_confounds_wf()
-
fmriprep.workflows.bold.base.
init_func_derivatives_wf
(bids_root, cifti_output, freesurfer, metadata, output_dir, spaces, use_aroma, name='func_derivatives_wf')[source]¶ Set up a battery of datasinks to store derivatives in the right location.
- Parameters
bids_root (
str
) – Original BIDS dataset path.cifti_output (
bool
) – Whether the--cifti-output
flag was set.freesurfer (
bool
) – Whether FreeSurfer anatomical processing was run.metadata (
dict
) – Metadata dictionary associated to the BOLD run.output_dir (
str
) – Where derivatives should be written out to.spaces (
SpatialReferences
) – A container for storing, organizing, and parsing spatial normalizations. Composed ofReference
objects representing spatial references. EachReference
contains a space, which is a string of either TemplateFlow template IDs (e.g.,MNI152Lin
,MNI152NLin6Asym
,MNIPediatricAsym
), nonstandard references (e.g.,T1w
oranat
,sbref
,run
, etc.), or a custom template located in the TemplateFlow root directory. EachReference
may also contain a spec, which is a dictionary with template specifications (e.g., a specification of{'resolution': 2}
would lead to resampling on a 2mm resolution of the space).use_aroma (
bool
) – Whether--use-aroma
flag was set.name (
str
) – This workflow’s identifier (default:func_derivatives_wf
).
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]¶ Build a workflow to estimate head-motion parameters.
This workflow estimates the motion parameters to perform HMC over the input BOLD image.
- Workflow Graph
(Source code, png, svg, pdf)
- Parameters
- 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¶
Generate T2* map from multi-echo BOLD images¶
-
fmriprep.workflows.bold.t2s.
init_bold_t2s_wf
(echo_times, mem_gb, omp_nthreads, t2s_coreg=False, name='bold_t2s_wf')[source]¶ Combine multiple echos of ME-EPI.
This workflow wraps the tedana T2* workflow to optimally combine multiple echos and derive a T2* map for optional use as a coregistration target. The following steps are performed:
HMC on individual echo files.
Compute the T2* map
Create an optimally combined ME-EPI time series
- Parameters
echo_times (
list
) – list of TEs associated with each echomem_gb (
float
) – Size of BOLD file in GBomp_nthreads (
int
) – Maximum number of threads an individual process may uset2s_coreg (
bool
) – Use the calculated T2*-map for T2*-driven coregistrationname (
str
) – Name of workflow (default:bold_t2s_wf
)
- Inputs
bold_file – list of individual echo files
- Outputs
bold – the optimally combined time series for all supplied echos
bold_mask – the binarized, skull-stripped adaptive T2* map
bold_ref_brain – the adaptive T2* map
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]¶ Build a workflow to run same-subject, BOLD-to-T1w image-registration.
Calculates the registration between a reference BOLD image and T1w-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.- Workflow Graph
(Source code, png, svg, pdf)
- Parameters
freesurfer (
bool
) – Enable FreeSurfer functional registration (bbregister)use_bbr (
bool
or None) – Enable/disable boundary-based registration refinement. IfNone
, 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 GBomp_nthreads (
int
) – Maximum number of threads an individual process may usename (
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 T1write_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 unwarpedt1w_brain – Skull-stripped
t1w_preproc
t1w_dseg – 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
fsnative2t1w_xfm – 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)
-
fmriprep.workflows.bold.registration.
init_bold_t1_trans_wf
(freesurfer, mem_gb, omp_nthreads, multiecho=False, use_fieldwarp=False, use_compression=True, name='bold_t1_trans_wf')[source]¶ Co-register the reference BOLD image to T1w-space.
The workflow uses BBR.
- Workflow Graph
(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 T1multiecho (
bool
) – If multiecho data was supplied, HMC already performedmem_gb (
float
) – Size of BOLD file in GBomp_nthreads (
int
) – Maximum number of threads an individual process may useuse_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 unwarpedref_bold_mask – Skull-stripping mask of reference image
t1w_brain – Skull-stripped bias-corrected structural template image
t1w_mask – Mask of the skull-stripped template image
t1w_aseg – FreeSurfer’s
aseg.mgz
atlas projected into the T1w reference (only ifrecon-all
was run).t1w_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 formatitk_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_t1_ref – Reference, contrast-enhanced summary of the motion-corrected BOLD series in T1w 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).
-
fmriprep.workflows.bold.registration.
init_bbreg_wf
(use_bbr, bold2t1w_dof, omp_nthreads, name='bbreg_wf')[source]¶ Build a workflow to run FreeSurfer’s
bbregister
.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. Theuse_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.- Workflow Graph
(Source code, png, svg, pdf)
- Parameters
- Inputs
in_file – Reference BOLD image to be registered
fsnative2t1w_xfm – 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)
t1w_brain – Unused (see
init_fsl_bbr_wf()
)t1w_dseg – 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]¶ Build a workflow to run FSL’s
flirt
.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.- Workflow Graph
(Source code, png, svg, pdf)
- Parameters
- Inputs
in_file – Reference BOLD image to be registered
t1w_brain – Skull-stripped T1-weighted structural image
t1w_dseg – FAST segmentation of
t1w_brain
fsnative2t1w_xfm – 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 T1w 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, surface_spaces, medial_surface_nan, name='bold_surf_wf')[source]¶ Sample 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.
- Workflow Graph
(Source code, png, svg, pdf)
- Parameters
surface_spaces (
list
) – List of FreeSurfer surface-spaces (eitherfsaverage{3,4,5,6,}
orfsnative
) the functional images are to be resampled to. Forfsnative
, 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
t1w_preproc – Bias-corrected structural template image
subjects_dir – FreeSurfer SUBJECTS_DIR
subject_id – FreeSurfer subject ID
t1w2fsnative_xfm – 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_std_trans_wf
(freesurfer, mem_gb, omp_nthreads, spaces, name='bold_std_trans_wf', use_compression=True, use_fieldwarp=False)[source]¶ Sample fMRI into standard space with a single-step resampling of the original BOLD series.
Important
This workflow provides two outputnodes. One output node (with name
poutputnode
) will be parameterized in a Nipype sense (see Nipype iterables), and a second node (outputnode
) will collapse the parameterized outputs into synchronous lists of the output fields listed below.- Workflow Graph
(Source code, png, svg, pdf)
- Parameters
freesurfer (
bool
) – Whether to generate FreeSurfer’s aseg/aparc segmentations on BOLD space.mem_gb (
float
) – Size of BOLD file in GBomp_nthreads (
int
) – Maximum number of threads an individual process may usespaces (
SpatialReferences
) – A container for storing, organizing, and parsing spatial normalizations. Composed ofReference
objects representing spatial references. EachReference
contains a space, which is a string of either TemplateFlow template IDs (e.g.,MNI152Lin
,MNI152NLin6Asym
,MNIPediatricAsym
), nonstandard references (e.g.,T1w
oranat
,sbref
,run
, etc.), or a custom template located in the TemplateFlow root directory. EachReference
may also contain a spec, which is a dictionary with template specifications (e.g., a specification of{'resolution': 2}
would lead to resampling on a 2mm resolution of the space).name (
str
) – Name of workflow (default:bold_std_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
anat2std_xfm – List of anatomical-to-standard space transforms generated during spatial normalization.
bold_aparc – FreeSurfer’s
aparc+aseg.mgz
atlas projected into the T1w reference (only ifrecon-all
was run).bold_aseg – FreeSurfer’s
aseg.mgz
atlas projected into the T1w reference (only ifrecon-all
was run).bold_mask – Skull-stripping mask of reference image
bold_split – Individual 3D volumes, not motion corrected
fieldwarp – a DFM in ITK format
hmc_xforms – List of affine transforms aligning each volume to
ref_image
in ITK formatitk_bold_to_t1 – Affine transform from
ref_bold_brain
to T1 space (ITK format)name_source – BOLD series NIfTI file Used to recover original information lost during processing
templates – List of templates that were applied as targets during spatial normalization.
- Outputs
bold_std – BOLD series, resampled to template space
bold_std_ref – Reference, contrast-enhanced summary of the BOLD series, resampled to template space
bold_mask_std – BOLD series mask in template space
bold_aseg_std – FreeSurfer’s
aseg.mgz
atlas, in template space at the BOLD resolution (only ifrecon-all
was run)bold_aparc_std – FreeSurfer’s
aparc+aseg.mgz
atlas, in template space at the BOLD resolution (only ifrecon-all
was run)template – Template identifiers synchronized correspondingly to previously described outputs.
-
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]¶ Resample in native (original) space.
This workflow resamples the input fMRI in its native (original) space in a “single shot” from the original BOLD series.
- Workflow Graph
(Source code, png, svg, pdf)
- Parameters
mem_gb (
float
) – Size of BOLD file in GBomp_nthreads (
int
) – Maximum number of threads an individual process may usename (
str
) – Name of workflow (default:bold_std_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 MNIsplit_file (
bool
) – Whether the input file should be splitted (it is a 4D file) or it is a list of 3D files (defaultFalse
, 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 formatfieldwarp – 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, regressors_all_comps, regressors_dvars_th, regressors_fd_th, name='bold_confs_wf')[source]¶ Build a workflow to generate and write out confounding signals.
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
,white_matter
,global_signal
)DVARS - original and standardized variants (
dvars
,std_dvars
)Framewise displacement, based on head-motion parameters (
framewise_displacement
)Temporal CompCor (
t_comp_cor_XX
)Anatomical CompCor (
a_comp_cor_XX
)Cosine basis set for high-pass filtering w/ 0.008 Hz cut-off (
cosine_XX
)Non-steady-state volumes (
non_steady_state_XX
)Estimated head-motion parameters, in mm and rad (
trans_x
,trans_y
,trans_z
,rot_x
,rot_y
,rot_z
)
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.
- Workflow Graph
(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 FoVmetadata (
dict
) – BIDS metadata for BOLD filename (
str
) – Name of workflow (default:bold_confs_wf
)regressors_all_comps (
bool
) – Indicates whether CompCor decompositions should return all components instead of the minimal number of components necessary to explain 50 percent of the variance in the decomposition mask.regressors_dvars_th (
float
) – Criterion for flagging DVARS outliersregressors_fd_th (
float
) – Criterion for flagging framewise displacement outliers
- 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
skip_vols – number of non steady state volumes
t1w_mask – Mask of the skull-stripped template image
t1w_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.
confounds_metadata – Confounds metadata dictionary.
-
fmriprep.workflows.bold.confounds.
init_ica_aroma_wf
(mem_gb, metadata, omp_nthreads, aroma_melodic_dim=-200, err_on_aroma_warn=False, name='ica_aroma_wf', susan_fwhm=6.0, use_fieldwarp=True)[source]¶ Build a workflow that runs ICA-AROMA.
This workflow wraps ICA-AROMA to identify and remove motion-related independent components from a BOLD time series.
The following steps are performed:
Remove non-steady state volumes from the bold series.
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 spaceCalculate 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.
- Workflow Graph
(Source code, png, svg, pdf)
- Parameters
metadata (
dict
) – BIDS metadata for BOLD filemem_gb (
float
) – Size of BOLD file in GBomp_nthreads (
int
) – Maximum number of threads an individual process may usename (
str
) – Name of workflow (default:bold_tpl_trans_wf
)susan_fwhm (
float
) – Kernel width (FWHM in mm) for the smoothing step with FSLsusan
(default: 6.0mm)use_fieldwarp (
bool
) – Include SDC warp in single-shot transform from BOLD to MNIerr_on_aroma_warn (
bool
) – Do not fail on ICA-AROMA errorsaroma_melodic_dim (
int
) – Set the dimensionality of the MELODIC ICA decomposition. Negative numbers set a maximum on automatic dimensionality estimation. Positive numbers set an exact number of components to extract. (default: -200, i.e., estimate <=200 components)
- Inputs
itk_bold_to_t1 – Affine transform from
ref_bold_brain
to T1 space (ITK format)anat2std_xfm – ANTs-compatible affine-and-warp transform file
name_source – BOLD series NIfTI file Used to recover original information lost during processing
skip_vols – number of non steady state volumes
bold_split – Individual 3D BOLD volumes, not motion corrected
bold_mask – BOLD series mask in template space
hmc_xforms – List of affine transforms aligning each volume to
ref_image
in ITK formatfieldwarp – a DFM in ITK format
movpar_file – SPM-formatted motion parameters file
- 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