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
_images/api-1.png

(Source code, png, svg, pdf)

Parameters

  • anat_only (bool) – Disable functional workflows

  • bold2t1w_dof (6, 9 or 12) – Degrees-of-freedom for BOLD-T1w registration

  • cifti_output (bool) – Generate bold CIFTI file in output spaces

  • debug (bool) – Enable debugging outputs

  • dummy_scans (int or None) – Number of volumes to consider as non steady state

  • echo_idx (int or None) – Index of echo to preprocess in multiecho BOLD series, or None to preprocess all

  • err_on_aroma_warn (bool) – Do not fail on ICA-AROMA errors

  • fmap_bspline (bool) – Experimental: Fit B-Spline field using least-squares

  • fmap_demean (bool) – Demean voxel-shift map during unwarp

  • force_syn (bool) – Temporary: Always run SyN-based SDC

  • freesurfer (bool) – Enable FreeSurfer surface reconstruction (may increase runtime)

  • hires (bool) – Enable sub-millimeter preprocessing in FreeSurfer

  • ignore (list) – Preprocessing steps to skip (may include “slicetiming”, “fieldmaps”)

  • layout (BIDSLayout) – BIDS dataset layout

  • longitudinal (bool) – Treat multiple sessions as longitudinal (may increase runtime) See sub-workflows for specific differences

  • low_mem (bool) – Write uncompressed .nii files in some cases to reduce memory usage

  • medial_surface_nan (bool) – Replace medial wall values with NaNs on functional GIFTI files

  • omp_nthreads (int) – Maximum number of threads an individual process may use

  • output_dir (str) – Directory in which to save derivatives

  • regressors_all_comps (bool) – Return all CompCor component time series instead of the top fraction

  • regressors_dvars_th (float) – Criterion for flagging DVARS outliers

  • regressors_fd_th (float) – Criterion for flagging framewise displacement outliers

  • run_uuid (str) – Unique identifier for execution instance

  • skull_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 1

  • spaces (SpatialReferences) – A container for storing, organizing, and parsing spatial normalizations. Composed of Reference objects representing spatial references. Each Reference contains a space, which is a string of either TemplateFlow template IDs (e.g., MNI152Lin, MNI152NLin6Asym, MNIPediatricAsym), nonstandard references (e.g., T1w or anat, sbref, run, etc.), or a custom template located in the TemplateFlow root directory. Each Reference 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 labels

  • t2s_coreg (bool) – For multi-echo EPI, use the calculated T2*-map for T2*-driven coregistration

  • task_id (str or None) – Task ID of BOLD series to preprocess, or None to preprocess all

  • use_aroma (bool) – Perform ICA-AROMA on MNI-resampled functional series

  • use_bbr (bool or None) – Enable/disable boundary-based registration refinement. If None, 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 files

  • bids_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
_images/api-2.png

(Source code, png, svg, pdf)

Parameters

  • anat_only (bool) – Disable functional workflows

  • aroma_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 spaces

  • debug (bool) – Enable debugging outputs

  • dummy_scans (int or None) – Number of volumes to consider as non steady state

  • echo_idx (int or None) – Index of echo to preprocess in multiecho BOLD series, or None to preprocess all

  • err_on_aroma_warn (bool) – Do not fail on ICA-AROMA errors

  • fmap_bspline (bool) – Experimental: Fit B-Spline field using least-squares

  • fmap_demean (bool) – Demean voxel-shift map during unwarp

  • force_syn (bool) – Temporary: Always run SyN-based SDC

  • freesurfer (bool) – Enable FreeSurfer surface reconstruction (may increase runtime)

  • hires (bool) – Enable sub-millimeter preprocessing in FreeSurfer

  • ignore (list) – Preprocessing steps to skip (may include “slicetiming”, “fieldmaps”)

  • layout (BIDSLayout) – BIDS dataset layout

  • longitudinal (bool) – Treat multiple sessions as longitudinal (may increase runtime) See sub-workflows for specific differences

  • low_mem (bool) – Write uncompressed .nii files in some cases to reduce memory usage

  • medial_surface_nan (bool) – Replace medial wall values with NaNs on functional GIFTI files

  • name (str) – Name of workflow

  • omp_nthreads (int) – Maximum number of threads an individual process may use

  • output_dir (str) – Directory in which to save derivatives

  • reportlets_dir (str) – Directory in which to save reportlets

  • regressors_all_comps (bool) – Return all CompCor component time series instead of the top fraction

  • regressors_dvars_th (float) – Criterion for flagging DVARS outliers

  • regressors_fd_th (float) – Criterion for flagging framewise displacement outliers

  • 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

  • skull_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 labels

  • t2s_coreg (bool) – For multi-echo EPI, use the calculated T2*-map for T2*-driven coregistration

  • spaces (SpatialReferences) – A container for storing, organizing, and parsing spatial normalizations. Composed of Reference objects representing spatial references. Each Reference contains a space, which is a string of either TemplateFlow template IDs (e.g., MNI152Lin, MNI152NLin6Asym, MNIPediatricAsym), nonstandard references (e.g., T1w or anat, sbref, run, etc.), or a custom template located in the TemplateFlow root directory. Each Reference 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, or None to preprocess all

  • use_aroma (bool) – Perform ICA-AROMA on MNI-resampled functional series

  • use_bbr (bool or None) – Enable/disable boundary-based registration refinement. If None, 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
_images/api-3.png

(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 file

  • cifti_output (bool) – Generate bold CIFTI file in output spaces

  • debug (bool) – Enable debugging outputs

  • dummy_scans (int or None) – Number of volumes to consider as non steady state

  • err_on_aroma_warn (bool) – Do not crash on ICA-AROMA errors

  • fmap_bspline (bool) – Experimental: Fit B-Spline field using least-squares

  • fmap_demean (bool) – Demean voxel-shift map during unwarp

  • force_syn (bool) – Temporary: Always run SyN-based SDC

  • freesurfer (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 usage

  • medial_surface_nan (bool) – Replace medial wall values with NaNs on functional GIFTI files

  • omp_nthreads (int) – Maximum number of threads an individual process may use

  • output_dir (str) – Directory in which to save derivatives

  • regressors_all_comps (bool) – Return all CompCor component time series instead of the top fraction

  • regressors_dvars_th (float) – Criterion for flagging DVARS outliers

  • regressors_fd_th (float) – Criterion for flagging framewise displacement outliers

  • reportlets_dir (str) – Absolute path of a directory in which reportlets will be temporarily stored

  • spaces (SpatialReferences) – A container for storing, organizing, and parsing spatial normalizations. Composed of Reference objects representing spatial references. Each Reference contains a space, which is a string of either TemplateFlow template IDs (e.g., MNI152Lin, MNI152NLin6Asym, MNIPediatricAsym), nonstandard references (e.g., T1w or anat, sbref, run, etc.), or a custom template located in the TemplateFlow root directory. Each Reference 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 coregistration

  • use_aroma (bool) – Perform ICA-AROMA on MNI-resampled functional series

  • use_bbr (bool or None) – Enable/disable boundary-based registration refinement. If None, test BBR result for distortion before accepting. When using t2s_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 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

  • 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

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 of Reference objects representing spatial references. Each Reference contains a space, which is a string of either TemplateFlow template IDs (e.g., MNI152Lin, MNI152NLin6Asym, MNIPediatricAsym), nonstandard references (e.g., T1w or anat, sbref, run, etc.), or a custom template located in the TemplateFlow root directory. Each Reference 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
_images/api-4.png

(Source code, png, svg, pdf)

Parameters

  • mem_gb (float) – Size of BOLD file in GB

  • omp_nthreads (int) – Maximum number of threads an individual process may use

  • name (str) – Name of workflow (default: bold_hmc_wf)

Inputs

  • bold_file – BOLD series NIfTI file

  • raw_ref_image – Reference image to which BOLD series is motion corrected

Outputs

  • 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]

Create a workflow for STC.

This workflow performs STC over the input BOLD image.

Workflow Graph
_images/api-5.png

(Source code, png, svg, pdf)

Parameters

  • metadata (dict) – BIDS metadata for BOLD file

  • name (str) – Name of workflow (default: bold_stc_wf)

Inputs

  • bold_file – BOLD series NIfTI file

  • skip_vols – Number of non-steady-state volumes detected at beginning of bold_file

Outputs

stc_file – Slice-timing corrected BOLD series NIfTI file

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:

  1. HMC on individual echo files.

  2. Compute the T2* map

  3. Create an optimally combined ME-EPI time series

Parameters

  • echo_times (list) – 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

  • t2s_coreg (bool) – Use the calculated T2*-map for T2*-driven coregistration

  • name (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
_images/api-6.png

(Source code, png, svg, pdf)

Parameters

  • freesurfer (bool) – Enable FreeSurfer functional registration (bbregister)

  • use_bbr (bool or None) – Enable/disable boundary-based registration refinement. If None, test BBR result for distortion before accepting.

  • bold2t1w_dof (6, 9 or 12) – Degrees-of-freedom for BOLD-T1w registration

  • mem_gb (float) – Size of BOLD file in GB

  • omp_nthreads (int) – Maximum number of threads an individual process may use

  • name (str) – Name of workflow (default: bold_reg_wf)

  • use_compression (bool) – Save registered BOLD series as .nii.gz

  • use_fieldwarp (bool) – Include SDC warp in single-shot transform from BOLD to T1

  • 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

  • t1w_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
_images/api-7.png

(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

  • multiecho (bool) – If multiecho data was supplied, HMC already performed

  • 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

  • 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 if recon-all was run).

  • t1w_aparc – FreeSurfer’s aparc+aseg.mgz atlas projected into the T1w reference (only if recon-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_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 if recon-all was run).

  • bold_aparc_t1 – FreeSurfer’s aparc+aseg.mgz atlas, in T1w-space at the BOLD resolution (only if recon-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. The use_bbr option permits a high degree of control over registration. If False, standard, affine coregistration will be performed using FreeSurfer’s mri_coreg tool. If True, bbregister will be seeded with the initial transform found by mri_coreg (equivalent to running bbregister --init-coreg). If None, after bbregister is run, the resulting affine transform will be compared to the initial transform found by mri_coreg. Excessive deviation will result in rejecting the BBR refinement and accepting the original, affine registration.

Workflow Graph
_images/api-8.png

(Source code, png, svg, pdf)

Parameters

  • use_bbr (bool or None) – Enable/disable boundary-based registration refinement. If None, test BBR result for distortion before accepting.

  • bold2t1w_dof (6, 9 or 12) – Degrees-of-freedom for BOLD-T1w registration

  • name (str, optional) – Workflow name (default: bbreg_wf)

Inputs

  • in_file – Reference BOLD image to be registered

  • 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’s bbregister.

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

Workflow Graph
_images/api-9.png

(Source code, png, svg, pdf)

Parameters

  • use_bbr (bool or None) – Enable/disable boundary-based registration refinement. If None, test BBR result for distortion before accepting.

  • bold2t1w_dof (6, 9 or 12) – Degrees-of-freedom for BOLD-T1w registration

  • name (str, optional) – Workflow name (default: fsl_bbr_wf)

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
_images/api-10.png

(Source code, png, svg, pdf)

Parameters

  • surface_spaces (list) – List of FreeSurfer surface-spaces (either fsaverage{3,4,5,6,} or fsnative) the functional images are to be resampled to. For fsnative, images will be resampled to the individual subject’s native surface.

  • medial_surface_nan (bool) – Replace medial wall values with NaNs on functional GIFTI files

Inputs

  • source_file – Motion-corrected BOLD series in T1 space

  • 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
_images/api-11.png

(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 GB

  • omp_nthreads (int) – Maximum number of threads an individual process may use

  • spaces (SpatialReferences) – A container for storing, organizing, and parsing spatial normalizations. Composed of Reference objects representing spatial references. Each Reference contains a space, which is a string of either TemplateFlow template IDs (e.g., MNI152Lin, MNI152NLin6Asym, MNIPediatricAsym), nonstandard references (e.g., T1w or anat, sbref, run, etc.), or a custom template located in the TemplateFlow root directory. Each Reference 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 if recon-all was run).

  • bold_aseg – FreeSurfer’s aseg.mgz atlas projected into the T1w reference (only if recon-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 format

  • itk_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 if recon-all was run)

  • bold_aparc_std – FreeSurfer’s aparc+aseg.mgz atlas, in template space at the BOLD resolution (only if recon-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
_images/api-12.png

(Source code, png, svg, pdf)

Parameters

  • mem_gb (float) – Size of BOLD file in GB

  • omp_nthreads (int) – Maximum number of threads an individual process may use

  • name (str) – Name of workflow (default: bold_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

  • 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, 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:

  1. Region-wise average signal (csf, white_matter, global_signal)

  2. DVARS - original and standardized variants (dvars, std_dvars)

  3. Framewise displacement, based on head-motion parameters (framewise_displacement)

  4. Temporal CompCor (t_comp_cor_XX)

  5. Anatomical CompCor (a_comp_cor_XX)

  6. Cosine basis set for high-pass filtering w/ 0.008 Hz cut-off (cosine_XX)

  7. Non-steady-state volumes (non_steady_state_XX)

  8. 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
_images/api-13.png

(Source code, png, svg, pdf)

Parameters

  • mem_gb (float) – Size of BOLD file in GB - please note that this size should be calculated after resamplings that may extend the FoV

  • metadata (dict) – BIDS metadata for BOLD file

  • name (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 outliers

  • regressors_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:

  1. Remove non-steady state volumes from the bold series.

  2. Smooth data using FSL susan, with a kernel width FWHM=6.0mm.

  3. Run FSL melodic outside of ICA-AROMA to generate the report

  4. Run ICA-AROMA

  5. Aggregate identified motion components (aggressive) to TSV

  6. Return classified_motion_ICs and melodic_mix for user to complete non-aggressive denoising in T1w space

  7. 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.

Workflow Graph
_images/api-14.png

(Source code, png, svg, pdf)

Parameters

  • 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_tpl_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

  • err_on_aroma_warn (bool) – Do not fail on ICA-AROMA errors

  • aroma_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 format

  • fieldwarp – 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