Processing pipeline details¶
fmriprep adapts its pipeline depending on what data and metadata are
available and are used as the input.
For example, slice timing correction will be
performed only if the
SliceTiming metadata field is found for the input
A (very) high-level view of the simplest pipeline (for a single-band dataset with only one task, single-run, with no slice-timing information nor fieldmap acquisitions) is presented below:
The anatomical sub-workflow begins by constructing a template image by conforming any T1-weighted images to RAS orientation and a common voxel size, and, in the case of multiple images, merges them into a single template (see Longitudinal processing). This template is then skull-stripped, and the white matter/gray matter/cerebrospinal fluid segments are found. Finally, a non-linear registration to the MNI template space is estimated.
In the case of multiple sessions, T1w images are merged into a single template
image using FreeSurfer’s mri_robust_template.
This template may be unbiased, or equidistant from all source images, or
aligned to the first image (determined lexicographically by session label).
For two images, the additional cost of estimating an unbiased template is
trivial and is the default behavior, but, for greater than two images, the cost
can be a slowdown of an order of magnitude.
Therefore, in the case of three or more images,
templates aligned to the first image, unless passed the
flag, which forces the estimation of an unbiased template.
The preprocessed T1w image defines the
In the case of multiple T1w images, this space may not be precisely aligned
with any of the original images.
Reconstructed surfaces and functional datasets will be registered to the
T1w space, and not to the input images.
fmriprep uses FreeSurfer to reconstruct surfaces from T1w/T2w
If enabled, several steps in the
fmriprep pipeline are added or replaced.
All surface preprocessing may be disabled with the
If FreeSurfer reconstruction is performed, the reconstructed subject is placed in
<output dir>/freesurfer/sub-<subject_label>/ (see FreeSurfer Derivatives).
Surface reconstruction is performed in three phases.
The first phase initializes the subject with T1w and T2w (if available)
structural images and performs basic reconstruction (
autorecon1) with the
exception of skull-stripping.
For example, a subject with only one session with T1w and T2w images
would be processed by the following command:
$ recon-all -sd <output dir>/freesurfer -subjid sub-<subject_label> \ -i <bids-root>/sub-<subject_label>/anat/sub-<subject_label>_T1w.nii.gz \ -T2 <bids-root>/sub-<subject_label>/anat/sub-<subject_label>_T2w.nii.gz \ -autorecon1 \ -noskullstrip
The second phase imports the brainmask calculated in the T1w/T2w preprocessing
The final phase resumes reconstruction, using the T2w image to assist
in finding the pial surface, if available.
Reconstructed white and pial surfaces are included in the report.
If T1w voxel sizes are less than 1mm in all dimensions (rounding to nearest
.1mm), submillimeter reconstruction is used, unless disabled with
In order to bypass reconstruction in
fmriprep, place existing reconstructed
<output dir>/freesurfer prior to the run.
fmriprep will perform any missing
recon-all steps, but will not perform
any steps whose outputs already exist.
rh.midthickness surfaces are created in the subject
surf/ directory, corresponding to the surface half-way between the gray/white
boundary and the pial surface.
inflated surfaces are also
converted to GIFTI format and adjusted to be compatible with multiple software
packages, including FreeSurfer and the Connectome Workbench.
Preprocessing of BOLD files is split into multiple sub-workflows described below.
BOLD reference image estimation¶
This workflow estimates a reference image for a BOLD series. If T1-saturation effects (“dummy scans” or non-steady state volumes) are detected they are used as reference due to their superior tissue contrast. Otherwise a median of motion corrected subset of volumes is used. The reference image is used to calculate a brain mask for the BOLD signal using Nilearn. Further, the reference is fed to the head-motion estimation workflow and the registration workflow to map BOLD series into the T1w image of the same subject.
Using the previously estimated reference scan,
mcflirt is used to estimate head-motion.
As a result, one rigid-body transform with respect to
the reference image is written for each BOLD
Additionally, a list of 6-parameters (three rotations,
three translations) per time-step is written and fed to the
For a more accurate estimation of head-motion, we calculate its parameters
before any time-domain filtering (i.e. slice-timing correction),
as recommended in [Power2017].
Slice time correction¶
SliceTiming field is available within the input dataset metadata,
this workflow performs slice time correction prior to other signal resampling
Slice time correction is performed using AFNI
All slices are realigned in time to the middle of each TR.
Slice time correction can be disabled with the
command line argument.
If a BOLD series has fewer than
5 usable (steady-state) volumes, slice time correction will be disabled
for that run.
Susceptibility Distortion Correction (SDC)¶
One of the major problems that affects EPI data is the spatial distortion caused by the inhomogeneity of the field inside the scanner. Please refer to Susceptibility Distortion Correction (SDC) for details on the available workflows.
Pre-processed BOLD in native space¶
A new preproc BOLD series is generated from the slice-timing corrected or the original data (if STC was not applied) in the original space. All volumes in the BOLD series are resampled in their native space by concatenating the mappings found in previous correction workflows (HMC and SDC if excecuted) for a one-shot interpolation process. Interpolation uses a Lanczos kernel.
EPI to T1w registration¶
The reference EPI image of each run is aligned
bbregister routine to the reconstructed subject using the gray/white
matter boundary (FreeSurfer’s
If FreeSurfer processing is disabled, FSL
flirt is run with the
BBR cost function, using the
fast segmentation to establish the gray/white matter boundary.
EPI to MNI transformation¶
This sub-workflow concatenates the transforms calculated upstream (see Head-motion estimation, Susceptibility Distortion Correction (SDC) –if fieldmaps are available–, EPI to T1w registration, and a T1w-to-MNI transform from T1w/T2w preprocessing) to map the EPI image to standard MNI space. It also maps the T1w-based mask to MNI space.
Transforms are concatenated and applied all at once, with one interpolation (Lanczos) step, so as little information is lost as possible.
EPI sampled to FreeSurfer surfaces¶
If FreeSurfer processing is enabled, the motion-corrected functional series (after single shot resampling to T1w space) is sampled to the surface by averaging across the cortical ribbon. Specifically, at each vertex, the segment normal to the white-matter surface, extending to the pial surface, is sampled at 6 intervals and averaged.
Surfaces are generated for the “subject native” surface, as well as transformed to the
fsaverage template space.
All surface outputs are in GIFTI format.
Given a motion-corrected fMRI, a brain mask,
mcflirt movement parameters and a
segmentation, the discover_wf sub-workflow calculates potential
confounds per volume.
Calculated confounds include the mean global signal, mean tissue class signal,
tCompCor, aCompCor, Frame-wise Displacement, 6 motion parameters, DVARS, and, if
--use-aroma flag is enabled, the noise components identified by ICA-AROMA
(those to be removed by the “aggressive” denoising strategy).
Note: non-aggressive AROMA denoising is a fundamentally different procedure from its “aggressive” counterpart and cannot be performed only by using a set of noise regressors (a separate GLM with both noise and signal regressors needs to be used). Therefore instead of regressors FMRIPREP produces non-aggressive denoised 4D NIFTI files in the MNI space:
Additionally, the MELODIC mix and noise component indices will
be generated, so non-aggressive denoising can be manually performed in the T1w space with
fsl_regfilt -i sub-<subject_label>_task-<task_id>_bold_space-T1w_preproc.nii.gz \ -f $(cat sub-<subject_label>_task-<task_id>_bold_AROMAnoiseICs.csv) \ -d sub-<subject_label>_task-<task_id>_bold_MELODICmix.tsv \ -o sub-<subject_label>_task-<task_id>_bold_space-<space>_AromaNonAggressiveDenoised.nii.gz
A visualization of the AROMA component classification is also included in the HTML reports.