fMRIprep - Neurodesk

Author: Steffen Bollmann

Date: 17 Oct 2024

License:

Note: If this notebook uses neuroimaging tools from Neurocontainers, those tools retain their original licenses. Please see Neurodesk citation guidelines for details.

Citation and Resources¶

Tools included in this workflow¶

fMRIPrep:

Esteban, O., Markiewicz, C.J., Blair, R.W. et al. fMRIPrep: a robust preprocessing pipeline for functional MRI. Nat Methods 16, 111–116 (2019). Esteban et al. (2018)

Dataset¶

Flanker Dataset from OpenNeuro:

Kelly AMC and Uddin LQ and Biswal BB and Castellanos FX and Milham MP (2018). Flanker task (event-related). OpenNeuro Dataset ds000102
Kelly, A. M., Uddin, L. Q., Biswal, B. B., Castellanos, F. X., & Milham, M. P. (2008). Competition between functional brain networks mediates behavioral variability. NeuroImage, 39(1), 527–537. Kelly et al. (2008)

Educational resources¶

fMRIPrep documentation

Demonstrationg fMRIprep on Neurodesk¶

Preprocessing is a critical step in fMRI analysis, converting raw fMRI data into a form ready for statistical analysis. fMRIPrep is a robust, automated preprocessing pipeline that performs basic processing steps (coregistration, normalization, unwarping, noise component extraction, segmentation, skull-stripping, etc.), providing outputs that can be easily submitted to a variety of group level analyses, including task-based or resting-state fMRI, graph theory measures, and surface or volume-based statistics. It combines tools from well-known software packages including FSL, ANTs, FreeSurfer and AFNI, and generates quality reports that allow users to easily identify outliers

In this notebook, we demonstrate how to run fMRIPrep on a BIDS-formatted dataset and explore examples of the outputs it generates.

Load fMRIPrep and request FreeSurfer license¶

# load fmriprep
import module
import os
await module.load('fmriprep/24.1.0')
await module.list()

['fmriprep/24.1.0']

# Request a freesurfer license and store it in your homedirectory. This is just an exampe - please replace with your license id:
!echo "Steffen.Bollmann@cai.uq.edu.au" > ~/.license
!echo "21029" >> ~/.license
!echo "*Cqyn12sqTCxo" >> ~/.license
!echo "FSxgcvGkNR59Y" >> ~/.license

Download Data¶

!datalad install https://github.com/OpenNeuroDatasets/ds000102.git
!cd ds000102 && datalad get sub-08

Cloning:   0%|                             | 0.00/2.00 [00:00<?, ? candidates/s]
Enumerating: 0.00 Objects [00:00, ? Objects/s]
                                              
Counting:   0%|                               | 0.00/27.0 [00:00<?, ? Objects/s]
                                                                                
Compressing:   0%|                            | 0.00/23.0 [00:00<?, ? Objects/s]
                                                                                
Receiving:   0%|                             | 0.00/2.15k [00:00<?, ? Objects/s]
                                                                                
Resolving:   0%|                                | 0.00/537 [00:00<?, ? Deltas/s]
[INFO   ] Remote origin not usable by git-annex; setting annex-ignore 
[INFO   ] https://github.com/OpenNeuroDatasets/ds000102.git/config download failed: Not Found 
[INFO   ] access to 1 dataset sibling s3-PRIVATE not auto-enabled, enable with:
| 		datalad siblings -d "/home/jovyan/workspace/books/examples/functional_imaging/ds000102" enable -s s3-PRIVATE 
install(ok): /home/jovyan/workspace/books/examples/functional_imaging/ds000102 (dataset)
Total:   0%|                                   | 0.00/67.8M [00:00<?, ? Bytes/s]
Get sub-08/a .. 8_T1w.nii.gz:   0%|            | 0.00/10.6M [00:00<?, ? Bytes/s]
Get sub-08/a .. 8_T1w.nii.gz:   0%|    | 33.4k/10.6M [00:00<01:06, 157k Bytes/s]
Get sub-08/a .. 8_T1w.nii.gz:   1%|    | 68.2k/10.6M [00:00<01:05, 161k Bytes/s]
Get sub-08/a .. 8_T1w.nii.gz:   1%|     | 138k/10.6M [00:00<00:43, 237k Bytes/s]
Get sub-08/a .. 8_T1w.nii.gz:   3%|▏    | 277k/10.6M [00:00<00:25, 402k Bytes/s]
Get sub-08/a .. 8_T1w.nii.gz:   5%|▎    | 538k/10.6M [00:01<00:14, 701k Bytes/s]
Get sub-08/a .. 8_T1w.nii.gz:  10%|▎  | 1.06M/10.6M [00:01<00:07, 1.30M Bytes/s]
Get sub-08/a .. 8_T1w.nii.gz:  20%|▌  | 2.09M/10.6M [00:01<00:03, 2.46M Bytes/s]
Get sub-08/a .. 8_T1w.nii.gz:  35%|█  | 3.66M/10.6M [00:01<00:01, 4.84M Bytes/s]
Get sub-08/a .. 8_T1w.nii.gz:  54%|█▋ | 5.74M/10.6M [00:01<00:00, 6.60M Bytes/s]
Get sub-08/a .. 8_T1w.nii.gz:  73%|██▏| 7.72M/10.6M [00:02<00:00, 7.52M Bytes/s]
Get sub-08/a .. 8_T1w.nii.gz:  93%|██▊| 9.80M/10.6M [00:02<00:00, 8.25M Bytes/s]
                                                                                
Get sub-08/a .. 8_T1w.nii.gz:   0%|            | 0.00/10.6M [00:00<?, ? Bytes/s]
Total:  16%|████                      | 10.6M/67.8M [00:03<00:19, 2.91M Bytes/s]
Get sub-08/f .. _bold.nii.gz:   0%|            | 0.00/28.6M [00:00<?, ? Bytes/s]
Get sub-08/f .. _bold.nii.gz:  10%|▎  | 2.96M/28.6M [00:00<00:01, 14.8M Bytes/s]
Get sub-08/f .. _bold.nii.gz:  16%|▍  | 4.55M/28.6M [00:00<00:02, 10.9M Bytes/s]
Get sub-08/f .. _bold.nii.gz:  21%|▋  | 6.07M/28.6M [00:00<00:01, 12.2M Bytes/s]
Get sub-08/f .. _bold.nii.gz:  30%|▉  | 8.48M/28.6M [00:00<00:01, 11.8M Bytes/s]
Get sub-08/f .. _bold.nii.gz:  37%|█  | 10.5M/28.6M [00:01<00:02, 7.76M Bytes/s]
Get sub-08/f .. _bold.nii.gz:  42%|█▎ | 12.0M/28.6M [00:01<00:02, 7.53M Bytes/s]
Get sub-08/f .. _bold.nii.gz:  45%|█▎ | 13.0M/28.6M [00:01<00:02, 7.78M Bytes/s]
Get sub-08/f .. _bold.nii.gz:  51%|█▌ | 14.5M/28.6M [00:01<00:01, 9.04M Bytes/s]
Get sub-08/f .. _bold.nii.gz:  57%|█▋ | 16.3M/28.6M [00:01<00:01, 8.81M Bytes/s]
Get sub-08/f .. _bold.nii.gz:  64%|█▉ | 18.4M/28.6M [00:01<00:01, 9.27M Bytes/s]
Get sub-08/f .. _bold.nii.gz:  72%|██▏| 20.7M/28.6M [00:02<00:00, 9.69M Bytes/s]
Get sub-08/f .. _bold.nii.gz:  79%|██▎| 22.6M/28.6M [00:02<00:00, 9.45M Bytes/s]
Get sub-08/f .. _bold.nii.gz:  87%|██▌| 24.8M/28.6M [00:02<00:00, 9.75M Bytes/s]
Get sub-08/f .. _bold.nii.gz:  93%|██▊| 26.7M/28.6M [00:02<00:00, 9.59M Bytes/s]
                                                                                
Get sub-08/f .. _bold.nii.gz:   0%|            | 0.00/28.6M [00:00<?, ? Bytes/s]
Total:  58%|███████████████           | 39.2M/67.8M [00:07<00:05, 5.51M Bytes/s]
Get sub-08/f .. _bold.nii.gz:   0%|            | 0.00/28.6M [00:00<?, ? Bytes/s]
Get sub-08/f .. _bold.nii.gz:   5%|▏  | 1.40M/28.6M [00:00<00:01, 14.0M Bytes/s]
Get sub-08/f .. _bold.nii.gz:  10%|▎  | 2.86M/28.6M [00:00<00:01, 14.3M Bytes/s]
Get sub-08/f .. _bold.nii.gz:  16%|▍  | 4.56M/28.6M [00:00<00:02, 10.7M Bytes/s]
Get sub-08/f .. _bold.nii.gz:  23%|▋  | 6.52M/28.6M [00:00<00:01, 13.5M Bytes/s]
Get sub-08/f .. _bold.nii.gz:  31%|▉  | 9.00M/28.6M [00:00<00:01, 10.0M Bytes/s]
Get sub-08/f .. _bold.nii.gz:  39%|█▏ | 11.1M/28.6M [00:00<00:01, 12.3M Bytes/s]
Get sub-08/f .. _bold.nii.gz:  45%|█▎ | 12.8M/28.6M [00:01<00:01, 10.6M Bytes/s]
Get sub-08/f .. _bold.nii.gz:  54%|█▋ | 15.6M/28.6M [00:01<00:01, 9.68M Bytes/s]
Get sub-08/f .. _bold.nii.gz:  62%|█▊ | 17.6M/28.6M [00:01<00:00, 11.5M Bytes/s]
Get sub-08/f .. _bold.nii.gz:  70%|██ | 19.9M/28.6M [00:01<00:00, 11.3M Bytes/s]
Get sub-08/f .. _bold.nii.gz:  76%|██▎| 21.6M/28.6M [00:01<00:00, 10.2M Bytes/s]
Get sub-08/f .. _bold.nii.gz:  83%|██▌| 23.9M/28.6M [00:02<00:00, 10.4M Bytes/s]
Get sub-08/f .. _bold.nii.gz:  91%|██▋| 26.0M/28.6M [00:02<00:00, 10.2M Bytes/s]
Get sub-08/f .. _bold.nii.gz:  99%|██▉| 28.3M/28.6M [00:02<00:00, 10.4M Bytes/s]
                                                                                
Get sub-08/f .. _bold.nii.gz:   0%|            | 0.00/28.6M [00:00<?, ? Bytes/s]
get(ok): sub-08/anat/sub-08_T1w.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-08/func/sub-08_task-flanker_run-1_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-08/func/sub-08_task-flanker_run-2_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-08 (directory)
action summary:
  get (ok: 4)

Run fMRIPrep¶

%%bash
# set up environment variables
export SUBJECTS_DIR=$PWD/fmriprep-freesurfer-dir
export APPTAINERENV_SUBJECTS_DIR=$SUBJECTS_DIR
export ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS=2 
export MPLCONFIGDIR=~/matplotlib-mpldir 

# create subjects directory
mkdir -p $SUBJECTS_DIR

# run fmriprep
fmriprep ds000102/ fmriprep-output participant \
--fs-license-file ~/.license \
--output-spaces T1w MNI152NLin2009cAsym fsaverage fsnative \
--participant-label 08 \
--nprocs $ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS \
--mem 10000 \
--skip_bids_validation \
--fs-subjects-dir $SUBJECTS_DIR \
-v

Fetching long content....

fMRIprep Results¶

The full result report is in fmriprep-output/sub-08.html and you can open this webpage in Jupyterlab or in the browser. Here a few items from the report as an example and for a quick check:

T1 and brain mask¶

Template T1-weighted image (if several T1w images were found), with contours delineating the detected brain mask and brain tissue segmentations.

from IPython.core.display import SVG
SVG(filename='fmriprep-output/sub-08/figures/sub-08_dseg.svg')

Surfaces¶

Surfaces (white and pial) reconstructed with FreeSurfer (recon-all) overlaid on the participant’s T1w template.

SVG(filename='fmriprep-output/sub-08/figures/sub-08_desc-reconall_T1w.svg')

EPI-space to T1-space¶

SVG(filename='fmriprep-output/sub-08/figures/sub-08_task-flanker_run-1_desc-coreg_bold.svg')

Brain mask and (anatomical/temporal) CompCor ROIs¶

Brain mask calculated on the BOLD signal (red contour), along with the regions of interest (ROIs) used for the estimation of physiological and movement confounding components that can be then used as nuisance regressors in analysis. The anatomical CompCor ROI (magenta contour) is a mask combining CSF and WM (white-matter), where voxels containing a minimal partial volume of GM have been removed. The temporal CompCor ROI (blue contour) contains the top 2% most variable voxels within the brain mask. The brain edge (or crown) ROI (green contour) picks signals outside but close to the brain, which are decomposed into 24 principal components.

SVG(filename='fmriprep-output/sub-08/figures/sub-08_task-flanker_run-1_desc-rois_bold.svg')

Bold Summary¶

Summary statistics are plotted, which may reveal trends or artifacts in the BOLD data. Global signals calculated within the whole-brain (GS), within the white-matter (WM) and within cerebro-spinal fluid (CSF) show the mean BOLD signal in their corresponding masks. DVARS and FD show the standardized DVARS and framewise-displacement measures for each time point. A carpet plot shows the time series for all voxels within the brain mask, or if --cifti-output was enabled, all grayordinates. Voxels are grouped into cortical (dark/light blue), and subcortical (orange) gray matter, cerebellum (green) and white matter and CSF (red), indicated by the color map on the left-hand side.

SVG(filename='fmriprep-output/sub-08/figures/sub-08_task-flanker_run-1_desc-carpetplot_bold.svg')

Dependencies in Jupyter/Python¶

Using the package watermark to document system environment and software versions used in this notebook, alongside the Neurodesktop version extracted from the JUPYTER_IMAGE or NEURODESKTOP_VERSION environment variables.

import os

%load_ext watermark

%watermark
%watermark --iversions

neurodesktop_version = (
    os.environ.get('JUPYTER_IMAGE', '').split(':')[-1] or
    os.environ.get('NEURODESKTOP_VERSION', 'unknown')
)

print(f"Neurodesktop version: {neurodesktop_version}")

Last updated: 2026-04-10T09:06:18.185091+00:00

Python implementation: CPython
Python version       : 3.13.9
IPython version      : 9.7.0

Compiler    : GCC 14.3.0
OS          : Linux
Release     : 5.15.0-171-generic
Machine     : x86_64
Processor   : x86_64
CPU cores   : 32
Architecture: 64bit

IPython: 9.7.0

Neurodesktop version: 2025-12-20

References¶

Esteban, O., Markiewicz, C. J., Blair, R. W., Moodie, C. A., Isik, A. I., Erramuzpe, A., Kent, J. D., Goncalves, M., DuPre, E., Snyder, M., Oya, H., Ghosh, S. S., Wright, J., Durnez, J., Poldrack, R. A., & Gorgolewski, K. J. (2018). fMRIPrep: a robust preprocessing pipeline for functional MRI. Nature Methods, 16(1), 111–116. 10.1038/s41592-018-0235-4
Kelly, A. M. C., Uddin, L. Q., Biswal, B. B., Castellanos, F. X., & Milham, M. P. (2008). Competition between functional brain networks mediates behavioral variability. NeuroImage, 39(1), 527–537. 10.1016/j.neuroimage.2007.08.008