Basic workflow (no fieldmaps)¶
fmriprep‘s basic pipeline is used on datasets for which there are only t1ws
and at least one functional (EPI) file, but no SBRefs or fieldmaps.
To force using this pipeline on datasets that do include fieldmaps and SBRefs
--ignore fieldmaps flag.
Several steps are added or modified if Surface preprocessing is enabled.
What It Does¶
High-level view of the basic pipeline:
t1w_preprocessing sub-workflow finds the skull stripping mask and the
white matter/gray matter/cerebrospinal fluid segments and finds a non-linear
warp to the MNI space.
If enabled, FreeSurfer surfaces are reconstructed from T1-weighted structural image(s), using the ANTs-extracted brain mask. See Reconstruction for details.
The EPI_HMC sub-workflow collects BIDS-formatted EPI files, performs head motion correction, and skullstripping. FSL MCFLIRT is used to estimate motion transformations and ANTs is used to apply them using Lanczos interpolation. Nilearn is used to perform skullstripping of the mean EPI image.
The ref_epi_t1_registration sub-workflow uses FSL FLIRT with the BBR cost function to find the transform that maps the EPI space into the T1-space.
If surface processing is enabled,
bbregister is used instead.
See Boundary-based Registration (BBR) for details.
The EPIMNITransformation sub-workflow uses the transform from ref_epi_t1_registration and a T1-to-MNI transform from t1w_preprocessing to map the EPI image to standardized MNI space. It also maps the t1w-based mask to MNI space.
Transforms are concatenated and applied all at once, with one interpolation step, so as little information is lost as possible.
Given a motion-corrected fMRI, a brain mask, MCFLIRT movement parameters and a segmentation, the ConfoundDiscoverer sub-workflow calculates potential confounds per volume.
Calculated confounds include the mean global signal, mean tissue class signal, tCompCor, aCompCor, Framewise Displacement, 6 motion parameters and DVARS.
fmriprep outputs summary reports, outputted to
These reports provide a quick way to make visual inspection of the results easy.
Each report is self contained and thus can be easily shared with collaborators (for example via email).
View a sample report.
There are additional files, called “Derivatives”, outputted to
See the BIDS spec for more information.
Derivatives related to t1w files are in the
*T1w_brainmask.nii.gzBrain mask derived using ANTS or AFNI, depending on the command flag
*T1w_space-MNI152NLin2009cAsym_brainmask.nii.gzSame as above, but in MNI space.
*T1w_dtissue.nii.gzTissue class map derived using FAST.
*T1w_preproc.nii.gzBias field corrected t1w file, using ANTS’ N4BiasFieldCorrection
*T1w_space-MNI152NLin2009cAsym_preproc.nii.gzSame as above, but in MNI space
*T1w_space-MNI152NLin2009cAsym_class-WM_probtissue.nii.gzProbability tissue maps, transformed into MNI space
*T1w_target-MNI152NLin2009cAsym_warp.h5Composite (warp and affine) transform to transform t1w into MNI space
Derivatives related to EPI files are in the
*bold_space-T1w_brainmask.nii.gzBrain mask for EPI files, calculated by nilearn on the average EPI volume, post-motion correction, in T1w space
*bold_space-MNI152NLin2009cAsym_brainmask.nii.gzSame as above, but in MNI space
*bold_confounds.tsvA tab-separated value file with one column per calculated confound and one row per timepoint/volume
*bold_space-T1w_preproc.nii.gzMotion-corrected (using MCFLIRT for estimation and ANTs for interpolation) EPI file in T1w space
*bold_space-MNI152NLin2009cAsym_preproc.nii.gzSame as above, but in MNI space
fmriprep uses FreeSurfer to reconstruct surfaces from T1/T2-weighted
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 T1- and T2-weighted (if available)
structural images and performs basic reconstruction (
autorecon1) with the
exception of skull-stripping.
For example, a subject with only one session with T1 and T2-weighted 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_preprocessing sub-workflow. The final phase resumes reconstruction, using the T2-weighted image to assist in finding the pial surface, if available:
$ recon-all -sd <output dir>/freesurfer -subjid sub-<subject_label> \ -all -T2pial
Reconstructed white and pial surfaces are included in the report.
If T1-weighted voxel sizes are less 1mm in all dimensions (rounding to nearest .1mm), submillimeter reconstruction is used.
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.
Boundary-based Registration (BBR)¶
The mean EPI image of each run is aligned to the reconstructed subject using
the gray/white matter boundary (FreeSurfer’s
If FreeSurfer processing is disabled, FLIRT is performed with the BBR cost function, using the FAST segmentation to establish the gray/white matter boundary.
A FreeSurfer subjects directory is created in
freesurfer/ fsaverage/ mri/ surf/ ... sub-<subject_label>/ mri/ surf/ ... ...
A copy of the
fsaverage subject distributed with the running version of
FreeSurfer is copied into this subjects directory.