Developers - API

The NiPreps community and contributing guidelines

fMRIPrep is a NiPreps application, and abides by the NiPreps Community guidelines. Please, make sure you have read and understood all the documentation provided in the NiPreps portal before you get started.

Setting up your development environment

We believe that fMRIPrep must be free to use, inspect, and critique. Correspondingly, you should be free to modify our software to improve it or adapt it to new use cases and we especially welcome contributions to improve it or its documentation.

We actively direct efforts into making the scrutiny and improvement processes as easy as possible. As part of such efforts, we maintain some tips and guidelines for developers to help minimize your burden if you want to modify the software.

Internal configuration system

A Python module to maintain unique, run-wide fMRIPrep settings.

This module implements the memory structures to keep a consistent, singleton config. Settings are passed across processes via filesystem, and a copy of the settings for each run and subject is left under <fmriprep_dir>/sub-<participant_id>/log/<run_unique_id>/fmriprep.toml. Settings are stored using ToML. The module has a to_filename() function to allow writing out the settings to hard disk in ToML format, which looks like:

Example file representation of fMRIPrep settings.

[environment]
cpu_count = 8
exec_env = "posix"
free_mem = 2.2
overcommit_policy = "heuristic"
overcommit_limit = "50%"
nipype_version = "1.5.0"
templateflow_version = "0.4.2"
version = "20.0.1"

[execution]
bids_dir = "ds000005/"
bids_description_hash = "5d42e27751bbc884eca87cb4e62b9a0cca0cd86f8e578747fe89b77e6c5b21e5"
boilerplate_only = false
fs_license_file = "/opt/freesurfer/license.txt"
fs_subjects_dir = "/opt/freesurfer/subjects"
log_dir = "/home/oesteban/tmp/fmriprep-ds005/out/fmriprep/logs"
log_level = 40
low_mem = false
md_only_boilerplate = false
notrack = true
output_dir = "/tmp"
output_spaces = "MNI152NLin2009cAsym:res-2 MNI152NLin2009cAsym:res-native fsaverage:den-10k fsaverage:den-30k"
reports_only = false
run_uuid = "20200306-105302_d365772b-fd60-4741-a722-372c2f558b50"
participant_label = [ "01",]
templateflow_home = "~/.cache/templateflow"
work_dir = "work/"
write_graph = false

[workflow]
anat_only = false
aroma_err_on_warn = false
aroma_melodic_dim = -200
bold2t1w_dof = 6
fmap_bspline = false
force_syn = false
hires = true
ignore = []
longitudinal = false
medial_surface_nan = false
project_goodvoxels = false
regressors_all_comps = false
regressors_dvars_th = 1.5
regressors_fd_th = 0.5
run_reconall = true
skull_strip_fixed_seed = false
skull_strip_template = "OASIS30ANTs"
t2s_coreg = false
use_aroma = false

[nipype]
crashfile_format = "txt"
get_linked_libs = false
memory_gb = 32
nprocs = 8
omp_nthreads = 8
plugin = "MultiProc"
resource_monitor = false
stop_on_first_crash = false

[nipype.plugin_args]
maxtasksperchild = 1
raise_insufficient = false

[execution.bids_filters.t1w]
reconstruction = "<Query.NONE: 1>"

[execution.bids_filters.t2w]
reconstruction = "<Query.NONE: 1>"

This config file is used to pass the settings across processes, using the load() function.

Configuration sections

class fmriprep.config.environment

Read-only options regarding the platform and environment.

Crawls runtime descriptive settings (e.g., default FreeSurfer license, execution environment, nipype and fMRIPrep versions, etc.). The environment section is not loaded in from file, only written out when settings are exported. This config section is useful when reporting issues, and these variables are tracked whenever the user does not opt-out using the --notrack argument.

cpu_count = 2

Number of available CPUs.

exec_docker_version = None

Version of Docker Engine.

exec_env = 'posix'

A string representing the execution platform.

free_mem = 3.0

Free memory at start.

nipype_version = '1.8.5'

Nipype’s current version.

overcommit_limit = '50%'

Linux’s kernel virtual memory overcommit limits.

overcommit_policy = 'heuristic'

Linux’s kernel virtual memory overcommit policy.

templateflow_version = '23.0.0'

The TemplateFlow client version installed.

version = '23.0.1'

fMRIPrep’s version.

class fmriprep.config.execution

Configure run-level settings.

anat_derivatives = None

A path where anatomical derivatives are found to fast-track sMRIPrep.

bids_database_dir = None

Path to the directory containing SQLite database indices for the input BIDS dataset.

bids_description_hash = None

Checksum (SHA256) of the dataset_description.json of the BIDS dataset.

bids_dir = None

An existing path to the dataset, which must be BIDS-compliant.

bids_filters = None

A dictionary of BIDS selection filters.

boilerplate_only = False

Only generate a boilerplate.

country_code = 'CAN'

Country ISO code used by carbon trackers.

debug = []

Debug mode(s).

echo_idx = None

Select a particular echo for multi-echo EPI datasets.

fmriprep_dir = None

Root of fMRIPrep BIDS Derivatives dataset. Depends on output_layout.

fs_license_file = None

An existing file containing a FreeSurfer license.

fs_subjects_dir = None

FreeSurfer’s subjects directory.

classmethod init()

Create a new BIDS Layout accessible with layout.

layout = None

A BIDSLayout object, see init().

log_dir = None

The path to a directory that contains execution logs.

log_level = 25

Output verbosity.

low_mem = None

Utilize uncompressed NIfTIs and other tricks to minimize memory allocation.

md_only_boilerplate = False

Do not convert boilerplate from MarkDown to LaTex and HTML.

me_output_echos = False

Output individual echo time series with slice, motion and susceptibility correction

notrack = False

Do not collect telemetry information for fMRIPrep.

output_dir = None

Folder where derivatives will be stored.

output_layout = None

Layout of derivatives within output_dir.

output_spaces = None

List of (non)standard spaces designated (with the --output-spaces flag of the command line) as spatial references for outputs.

participant_label = None

List of participant identifiers that are to be preprocessed.

reports_only = False

Only build the reports, based on the reportlets found in a cached working directory.

run_uuid = '20230324-201753_1519a9df-2056-4cb6-b3af-a9c63cbdd80f'

Unique identifier of this particular run.

sloppy = False

Run in sloppy mode (meaning, suboptimal parameters that minimize run-time).

task_id = None

Select a particular task from all available in the dataset.

templateflow_home = PosixPath('/home/docs/.cache/templateflow')

The root folder of the TemplateFlow client.

track_carbon = False

Tracks power draws using CodeCarbon package.

work_dir = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/fmriprep/checkouts/stable/docs/work')

Path to a working directory where intermediate results will be available.

write_graph = False

Write out the computational graph corresponding to the planned preprocessing.

class fmriprep.config.workflow

Configure the particular execution graph of this workflow.

anat_only = False

Execute the anatomical preprocessing only.

aroma_err_on_warn = None

Cast AROMA warnings to errors.

aroma_melodic_dim = None

Number of ICA components to be estimated by MELODIC (positive = exact, negative = maximum).

bold2t1w_dof = None

Degrees of freedom of the BOLD-to-T1w registration steps.

bold2t1w_init = 'register'

Whether to use standard coregistration (‘register’) or to initialize coregistration from the BOLD image-header (‘header’).

cifti_output = None

Generate HCP Grayordinates, accepts either '91k' (default) or '170k'.

dummy_scans = None

Set a number of initial scans to be considered nonsteady states.

fmap_bspline = None

Regularize fieldmaps with a field of B-Spline basis.

fmap_demean = None

Remove the mean from fieldmaps.

force_syn = None

Run fieldmap-less susceptibility-derived distortions estimation.

hires = None

Run FreeSurfer recon-all with the -hires flag.

ignore = None

Ignore particular steps for fMRIPrep.

longitudinal = False

Run FreeSurfer recon-all with the -logitudinal flag.

medial_surface_nan = None

Fill medial surface with NaNs when sampling.

project_goodvoxels = False

Exclude voxels with locally high coefficient of variation from sampling.

regressors_all_comps = None

Return all CompCor components.

regressors_dvars_th = None

Threshold for DVARS.

regressors_fd_th = None

Threshold for FD.

run_reconall = True

Run FreeSurfer’s surface reconstruction.

skull_strip_fixed_seed = False

Fix a seed for skull-stripping.

skull_strip_t1w = 'force'

Skip brain extraction of the T1w image (default is force, meaning that fMRIPrep will run brain extraction of the T1w).

skull_strip_template = 'OASIS30ANTs'

Change default brain extraction template.

slice_time_ref = 0.5

The time of the reference slice to correct BOLD values to, as a fraction acquisition time. 0 indicates the start, 0.5 the midpoint, and 1 the end of acquisition. The alias start corresponds to 0, and middle to 0.5. The default value is 0.5.

spaces = None

Keeps the SpatialReferences instance keeping standard and nonstandard spaces.

use_aroma = None

Run ICA-AROMA.

use_bbr = None

Run boundary-based registration for BOLD-to-T1w registration.

use_syn_sdc = None

Run fieldmap-less susceptibility-derived distortions estimation in the absence of any alternatives.

class fmriprep.config.nipype

Nipype settings.

crashfile_format = 'txt'

The file format for crashfiles, either text or pickle.

get_linked_libs = False

Run NiPype’s tool to enlist linked libraries for every interface.

classmethod get_plugin()

Format a dictionary for Nipype consumption.

classmethod init()

Set NiPype configurations.

memory_gb = None

Estimation in GB of the RAM this workflow can allocate at any given time.

nprocs = 2

Number of processes (compute tasks) that can be run in parallel (multiprocessing only).

omp_nthreads = None

Number of CPUs a single process can access for multithreaded execution.

plugin = 'MultiProc'

NiPype’s execution plugin.

plugin_args = {'maxtasksperchild': 1, 'raise_insufficient': False}

Settings for NiPype’s execution plugin.

resource_monitor = False

Enable resource monitor.

stop_on_first_crash = True

Whether the workflow should stop or continue after the first error.

Usage

A config file is used to pass settings and collect information as the execution graph is built across processes.

from fmriprep import config
config_file = config.execution.work_dir / '.fmriprep.toml'
config.to_filename(config_file)
# Call build_workflow(config_file, retval) in a subprocess
with Manager() as mgr:
    from .workflow import build_workflow
    retval = mgr.dict()
    p = Process(target=build_workflow, args=(str(config_file), retval))
    p.start()
    p.join()
config.load(config_file)
# Access configs from any code section as:
value = config.section.setting

Logging

class fmriprep.config.loggers

Keep loggers easily accessible (see init()).

cli = <Logger cli (WARNING)>

Command-line interface logging.

default = <RootLogger root (WARNING)>

The root logger.

classmethod init()

Set the log level, initialize all loggers into loggers.

• Add new logger levels (25: IMPORTANT, and 15: VERBOSE).

• Add a new sub-logger (cli).

• Logger configuration.

interface = <Logger nipype.interface (INFO)>

NiPype’s interface logger.

utils = <Logger nipype.utils (INFO)>

NiPype’s utils logger.

workflow = <Logger nipype.workflow (INFO)>

NiPype’s workflow logger.

Other responsibilities

The config is responsible for other conveniency actions.

• Switching Python’s multiprocessing to forkserver mode.

• Set up a filter for warnings as early as possible.

• Automated I/O magic operations. Some conversions need to happen in the store/load processes (e.g., from/to Path <-> str, BIDSLayout, etc.)

fmriprep.config.dumps()

Format config into toml.

fmriprep.config.from_dict(settings, init=True, ignore=None)

Read settings from a flat dictionary.

Parameters:

• setting (dict) – Settings to apply to any configuration

• init (bool or Container) – Initialize all, none, or a subset of configurations.

• ignore (Container) – Collection of keys in setting to ignore

fmriprep.config.get(flat=False)

Get config as a dict.

fmriprep.config.init_spaces(checkpoint=True)

Initialize the spaces setting.

fmriprep.config.load(filename, skip=None, init=True)

Load settings from file.

Parameters:

• filename (os.PathLike) – TOML file containing fMRIPrep configuration.

• skip (dict or None) – Sets of values to ignore during load, keyed by section name

• init (bool or Container) – Initialize all, none, or a subset of configurations.

fmriprep.config.to_filename(filename)

Write settings to file.

Workflows

fMRIPrep base processing workflows

fmriprep.workflows.base.init_fmriprep_wf()

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)

fmriprep.workflows.base.init_single_subject_wf(subject_id: str)

Organize 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)

Parameters:

subject_id (str) – Subject label for this single-subject workflow.

Parameters:

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(bold_file, has_fieldmap=False)

This workflow controls the functional preprocessing stages of fMRIPrep.

Workflow Graph

(Source code)

Parameters:

• bold_file – Path to NIfTI file (single echo) or list of paths to NIfTI files (multi-echo)

• has_fieldmap (bool) – Signals the workflow to use inputnode fieldmap files

Parameters:

• bold_file – BOLD series NIfTI file

• t1w_preproc – Bias-corrected structural template image

• 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_aseg – 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 – List of templates to target

• anat2std_xfm – List of transform files, collated with templates

• 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

Parameters:

• bold_t1 – BOLD series, resampled to T1w space

• bold_t1_ref – BOLD reference image, resampled to T1w space

• bold2anat_xfm – Affine transform from BOLD reference space to T1w space

• anat2bold_xfm – Affine transform from T1w space to BOLD reference space

• hmc_xforms – Affine transforms for each BOLD volume to the BOLD reference

• bold_mask_t1 – BOLD series mask in T1w space

• bold_aseg_t1 – FreeSurfer aseg resampled to match bold_t1

• bold_aparc_t1 – FreeSurfer aparc+aseg resampled to match bold_t1

• bold_std – BOLD series, resampled to template space

• bold_std_ref – BOLD reference image, resampled to template space

• bold_mask_std – BOLD series mask in template space

• bold_aseg_std – FreeSurfer aseg resampled to match bold_std

• bold_aparc_std – FreeSurfer aparc+aseg resampled to match bold_std

• bold_native – BOLD series, with distortion corrections applied (native space)

• bold_native_ref – BOLD reference image in native space

• bold_mask_native – BOLD series mask in native space

• bold_echos_native – Per-echo BOLD series, with distortion corrections applied

• bold_cifti – BOLD CIFTI image

• cifti_metadata – Path of metadata files corresponding to bold_cifti.

• surfaces – BOLD series, resampled to FreeSurfer surfaces

• t2star_bold – Estimated T2* map in BOLD native space

• t2star_t1 – Estimated T2* map in T1w space

• t2star_std – Estimated T2* map in template space

• confounds – TSV of confounds

• aroma_noise_ics – Noise components identified by ICA-AROMA

• melodic_mix – FSL MELODIC mixing matrix

• nonaggr_denoised_file – BOLD series, in native space, with non-agressive AROMA denoising applied

• confounds_metadata – Confounds metadata dictionary

See also

• init_bold_reference_wf()

• init_bold_stc_wf()

• init_bold_hmc_wf()

• init_bold_t2s_wf()

• init_t2s_reporting_wf()

• init_bold_t1_trans_wf()

• init_bold_reg_wf()

• init_bold_confs_wf()

• init_ica_aroma_wf()

• init_bold_std_trans_wf()

• init_bold_preproc_trans_wf()

• init_bold_surf_wf()

• init_fmap_wf()

• init_pepolar_unwarp_wf()

• init_phdiff_wf()

• init_syn_sdc_wf()

• init_sdc_unwarp_wf()

fmriprep.workflows.bold.base.init_func_derivatives_wf(bids_root: str, cifti_output: bool, freesurfer: bool, project_goodvoxels: bool, all_metadata: ty.List[dict], multiecho: bool, output_dir: str, spaces: SpatialReferences, use_aroma: bool, name='func_derivatives_wf')

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.

• project_goodvoxels (bool) – Whether the option was used to exclude voxels with locally high coefficient of variation, or that lie outside the cortical surfaces, from the surface projection.

• metadata (dict) – Metadata dictionary associated to the BOLD run.

• multiecho (bool) – Derivatives were generated from multi-echo time series.

• 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: float, omp_nthreads: int, name: str = 'bold_hmc_wf')

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)

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)

Parameters:

• bold_file – BOLD series NIfTI file

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

Parameters:

• xforms – ITKTransform file aligning each volume to ref_image

• movpar_file – MCFLIRT motion parameters, normalized to SPM format (X, Y, Z, Rx, Ry, Rz)

• rms_file – Framewise displacement as measured by fsl_motion_outliers [Jenkinson2002].

Slice-Timing Correction (STC) of BOLD images

fmriprep.workflows.bold.stc.init_bold_stc_wf(metadata: dict, name='bold_stc_wf')

Create a workflow for STC.

This workflow performs STC over the input BOLD image.

Workflow Graph

(Source code)

Parameters:

• metadata (dict) – BIDS metadata for BOLD file

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

Parameters:

• bold_file – BOLD series NIfTI file

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

Parameters:

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: Sequence[float], mem_gb: float, omp_nthreads: int, name: str = 'bold_t2s_wf')

Combine multiple echos of ME-EPI.

This workflow wraps the tedana T2* workflow to optimally combine multiple preprocessed echos and derive a T2^★ map. The following steps are performed: #. Compute the T2^★ map #. Create an optimally combined ME-EPI time series

Parameters:

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

Parameters:

• bold_file – list of individual echo files

• bold_mask – a binary mask to apply to the BOLD files

Parameters:

• bold – the optimally combined time series for all supplied echos

• t2star_map – the calculated T2^★ map

Registration workflows

fmriprep.workflows.bold.registration.init_bold_reg_wf(freesurfer: bool, use_bbr: bool, bold2t1w_dof: Literal[6, 9, 12], bold2t1w_init: Literal['register', 'header'], mem_gb: float, omp_nthreads: int, name: str = 'bold_reg_wf', sloppy: bool = False, use_compression: bool = True, write_report: bool = True)

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)

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

• bold2t1w_init (str, ‘header’ or ‘register’) – If 'header', use header information for initialization of BOLD and T1 images. If 'register', align volumes by their centers.

• 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

Parameters:

• 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

Parameters:

• 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: bool, mem_gb: float, omp_nthreads: int, use_compression: bool = True, name: str = 'bold_t1_trans_wf')

Co-register the reference BOLD image to T1w-space.

The workflow uses BBR.

Workflow Graph

(Source code)

Parameters:

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

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

Parameters:

• 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

Parameters:

• 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: bool, bold2t1w_dof: Literal[6, 9, 12], bold2t1w_init: Literal['register', 'header'], omp_nthreads: int, name: str = 'bbreg_wf')

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

(Source code)

Parameters:

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

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

• bold2t1w_init (str, ‘header’ or ‘register’) – If 'header', use header information for initialization of BOLD and T1 images. If 'register', align volumes by their centers.

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

Parameters:

• 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())

Parameters:

• 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: bool, bold2t1w_dof: Literal[6, 9, 12], bold2t1w_init: Literal['register', 'header'], omp_nthreads: int, sloppy: bool = False, name: str = 'fsl_bbr_wf')

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

(Source code)

Parameters:

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

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

• bold2t1w_init (str, ‘header’ or ‘register’) – If 'header', use header information for initialization of BOLD and T1 images. If 'register', align volumes by their centers.

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

Parameters:

• 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())

Parameters:

• 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: float, surface_spaces: List[str], medial_surface_nan: bool, project_goodvoxels: bool, name: str = 'bold_surf_wf')

Sample functional images to FreeSurfer surfaces.

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

If --project-goodvoxels is used, a “goodvoxels” BOLD mask, as described in [@hcppipelines], is generated and applied to the functional image before sampling to surface. After sampling, empty vertices are filled by dilating in data from the nearest “good” vertex, within a radius of 10 mm (as measured on the target midthickness surface).

Outputs are in GIFTI format.

Workflow Graph

(Source code)

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

• project_goodvoxels (bool) – Exclude voxels with locally high coefficient of variation, or that lie outside the cortical surfaces, from the surface projection.

Parameters:

• source_file – Motion-corrected BOLD series in T1 space

• subjects_dir – FreeSurfer SUBJECTS_DIR

• subject_id – FreeSurfer subject ID

• t1w2fsnative_xfm – LTA-style affine matrix translating from T1w to FreeSurfer-conformed subject space

• anat_ribbon – Cortical ribbon in T1w space

• t1w_mask – Mask of the skull-stripped T1w image

Parameters:

surfaces – BOLD series, resampled to FreeSurfer surfaces

fmriprep.workflows.bold.resampling.init_bold_std_trans_wf(freesurfer: bool, mem_gb: float, omp_nthreads: int, spaces: SpatialReferences, multiecho: bool, name: str = 'bold_std_trans_wf', use_compression: bool = True)

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)

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

Parameters:

• 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

• t2star – Estimated T2* map in BOLD native space

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

Parameters:

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

• t2star_std – Estimated T2* map in template space

• template – Template identifiers synchronized correspondingly to previously described outputs.

fmriprep.workflows.bold.resampling.init_bold_preproc_trans_wf(mem_gb: float, omp_nthreads: int, name: str = 'bold_preproc_trans_wf', use_compression: bool = True, use_fieldwarp: bool = False, interpolation: str = 'LanczosWindowedSinc')

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)

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

• interpolation (str) – Interpolation type to be used by ANTs’ applyTransforms (default "LanczosWindowedSinc")

Parameters:

• bold_file – Individual 3D volumes, not motion corrected

• 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

Parameters:

bold – BOLD series, resampled in native space, including all preprocessing

Calculate BOLD confounds

fmriprep.workflows.bold.confounds.init_bold_confs_wf(mem_gb: float, metadata: dict, regressors_all_comps: bool, regressors_dvars_th: float, regressors_fd_th: float, freesurfer: bool = False, name: str = 'bold_confs_wf')

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

(Source code)

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

Parameters:

• 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

• rmsd_file – Framewise displacement as measured by fsl_motion_outliers.

• 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

Parameters:

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

• crown_mask – Mask of brain edge voxels

fmriprep.workflows.bold.confounds.init_ica_aroma_wf(mem_gb: float, metadata: dict, omp_nthreads: int, aroma_melodic_dim: int = -200, err_on_aroma_warn: bool = False, name: str = 'ica_aroma_wf', susan_fwhm: float = 6.0)

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

(Source code)

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)

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

Parameters:

• 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

• movpar_file – SPM-formatted motion parameters file

Parameters:

• 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