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:
[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[source]
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.7
Free memory at start.
- nipype_version = '1.8.6'
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.2'
fMRIPrep’s version.
- class fmriprep.config.execution[source]
Configure run-level settings.
- anat_derivatives = None
A path where anatomical derivatives are found to fast-track sMRIPrep.
- bids_database_dir = None[source]
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_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.
- layout = None[source]
A
BIDSLayout
object, seeinit()
.
- 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_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 = '20230424-181320_b1041b51-57c0-408f-8e83-bd7358e96e06'
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')[source]
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')[source]
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[source]
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[source]
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[source]
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.
- 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
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.from_dict(settings, init=True, ignore=None)[source]
Read settings from a flat dictionary.
- fmriprep.config.load(filename, skip=None, init=True)[source]
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.
Workflows
fMRIPrep base processing workflows
- fmriprep.workflows.base.init_fmriprep_wf()[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
- fmriprep.workflows.base.init_single_subject_wf(subject_id: str)[source]
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
Pre-processing fMRI - BOLD signal workflows
Orchestrating the BOLD-preprocessing workflow
- fmriprep.workflows.bold.base.init_func_preproc_wf(bold_file, has_fieldmap=False)[source]
This workflow controls the functional preprocessing stages of fMRIPrep.
- Workflow Graph
- 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 matchbold_t1
bold_aparc_t1 – FreeSurfer
aparc+aseg
resampled to matchbold_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 matchbold_std
bold_aparc_std – FreeSurfer
aparc+aseg
resampled to matchbold_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_t2s_reporting_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')[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.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 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: float, omp_nthreads: int, name: str = '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
- Parameters:
- 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')[source]
Create a workflow for STC.
This workflow performs STC over the input BOLD image.
- Workflow Graph
- Parameters:
- 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')[source]
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:
- 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)[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
- 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
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 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
- Parameters:
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
- 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')[source]
Co-register the reference BOLD image to T1w-space.
The workflow uses BBR.
- Workflow Graph
- Parameters:
freesurfer (
bool
) – Enable FreeSurfer functional registration (bbregister)mem_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
)
- 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 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
- 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 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: bool, bold2t1w_dof: Literal[6, 9, 12], bold2t1w_init: Literal['register', 'header'], omp_nthreads: int, name: str = '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
- Parameters:
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
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')[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
- Parameters:
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
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')[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.
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
- 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 filesproject_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)[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
- 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
- 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 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
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 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.
- 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 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)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')[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
- 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 MNIinterpolation (
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 formatfieldwarp – 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')[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
- 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
- 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)[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
- 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)err_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)
- 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 formatmovpar_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