2.3 fmriPrep with Docker

Overview

This is the preprocessing step, run after your data is organized in BIDS. This note guides you through

Installing Docker and the Neurodesktop image

Running fMRIPrep (via Neurodesk modules, Singularity/Apptainer, and SLURM)

Reading the fMRIPrep HTML report and confounds table

Quality control with MRIQC is covered separately in 2.4 Quality Control with MRIQC (and is normally run on the raw data, before fMRIPrep).

Requirement

RAM : ≥ 16 GB (MRIQC/fMRIPrep are memory‑hungry)

DISK: ≥ 20 GB free (container + derivatives)

A FreeSurfer licence file (license.txt)—register free, save it in the project root.

1 · Install Docker

Windows / macOS (Docker Desktop)

Download the Docker Desktop installer from the official docs.
Run the installer → accept WSL 2 backend on Windows if prompted.
After reboot open Docker Desktop and ensure the whale icon is running in the system tray.

Verify:

docker run hello-world

2 · Pull & launch Neurodesktop

Instructions on installing and using the app: https://www.neurodesk.org/docs/getting-started/neurodesktop/neurodeskapp/

Launching the Neurodesk App

The Neurodesk App can be launched directly from your operating system’s application menu, or by running the neurodeskapp command in the command line.

Add a custom Data Directory

By default, /home/jovyan/neurodesktop-storage in the app (which is bound with local directory ~/neurodesktop-storage in Unix/MacOS or C:/neurodesktop-storage in Windows)

By choice, in the settings window below, select Additional Directory on the left side bar, click Change button to select the local directory, then click Apply & restart. The next time you start the app, the data from the local directory can be found in /home/jovyan/data. This is where you can read and analyze your MRI data.

Info

If you are using Windows it is currently not possible to mount external hard drives. We recommend copying data from the external drive to your local disk first and then processing it in Neurodesk.

After you successfully added an external folder, you should see a similar interface as follows. If you are familiar with the Jupyter Notebook interface, you can directly work here. If you prefer Desktop, then you can double click on Neurodesktop, it will open a virtual linux desktop for you.

Within the Neurodesktop, you can open related Apps.

Understand Neurodesktop Modules

What are modules?

Neurodesktop exposes each neuroimaging tool as an Lmod “module” backed by Singularity containers served over CVMFS.

Location
Modules live on CVMFS under /cvmfs/neurodesk.ardc.edu.au/neurodesk-modules/, with one folder per tool/version (e.g. fmriprep/2025-06-10) oai_citation:0‡GitHub.

MODULEPATH
The MODULEPATH environment variable points to /cvmfs/neurodesk.ardc.edu.au/containers/modules/, so that Lmod can find and load the correct wrapper scripts automatically oai_citation:1‡Docker Hub.

Loading modules
In any Neurodesktop terminal you can manually initialize and inspect available tools:

#module use /cvmfs/neurodesk.ardc.edu.au/neurodesk-modules/
module avail                     # list all tools/versions
module load fmriprep/24.1.1      # always pin an explicit version (not "latest") for reproducibility

3 Code inside the container with VS Code

The most handy App is Visual Studio Code. If you are familiar with VS Code, this would be your choice.

4. Preprocessing with fMRIPrep

fMRIPrep is a preprocessing pipeline for functional magnetic resonance imaging (fMRI) data. It offers an accessible, state-of-the-art interface that handles variations in scan protocols with minimal user input. The pipeline provides clear and comprehensive error and output reports. It performs essential processing steps, including coregistration, normalization, unwarping, noise component extraction, segmentation, and skull stripping. The outputs are easily suitable for various group-level analyses, including task-based and resting-state fMRI, graph theory measures, and surface or volume-based approaches.

A generic fMRI preprocessing pipeline looks as follows. fMRIPrep performs the blue steps but deliberately stops before spatial smoothing and intensity scaling — those are analysis choices you apply later (in your GLM), not part of fMRIPrep’s output:

flowchart TD
	A[Raw Data] --> B[Distortion correction]
	B --> C[Slice-Timing correction]
	A --> C
	C --> D[Registration and Normalization]
	D --> E[Alignment and Motion Correction]
	E --> I[Checking preprocessing]
	E -.-> F[Spatial Smoothing<br/>done later, not by fMRIPrep]
	F -.-> G[Masking and Scaling<br/>done later, not by fMRIPrep]
	style F stroke-dasharray: 5 5
	style G stroke-dasharray: 5 5

The fMRIPrep workflow takes as principal input the path of the dataset that is to be processed. The input dataset is required to be in valid BIDS format, and it must include at least one T1w structural image and (unless disabled with a flag) a BOLD series.

The standard parts of the command follow the BIDS-Apps definition, such as:

fmriprep data/bids_root/ out/ participant -w work.

4.1 Using module `fMRIPrep`

In the Neurodesk container, you can either edit the bash file (preferred) or run it directly with the command line.

# Set these once at top of script
export BIDS_DIR="${BIDS_DIR:-$HOME/data/ncp_2025}"   # BIDS dataset root
export DERIVS_DIR="${DERIVS_DIR:-$BIDS_DIR/derivatives}"
export FMRIPREP_DIR="${FMRIPREP_DIR:-$DERIVS_DIR/fmriprep}"
export WORK_DIR="${WORK_DIR:-$HOME/data/work}"       # scratch / working dir
export FS_LICENSE="${FS_LICENSE:-$BIDS_DIR/license.txt}"
export FMRIPREP_VERSION=24.1.1
 
module load fmriprep/${FMRIPREP_VERSION} # load pinned fmriprep module

Version pinning matters for reproducibility — see Software Versions.

Next, you can run fmriprep directly. For example, the following command runs preprocessing for the given BIDS_DIR with subject ID {001, 002, 003}, without Freesurfer surface preprocessing, and output spaces are MNI152NLin2009cAsym and local T1w spaces. It will use up to 6 threads with 16 GB of memory.

which MNI template?

MNI152NLin2009cAsym (fMRIPrep default) — non-linear average of 152 healthy adult brains, asymmetric, ICBM 2009c. Higher anatomical detail; the de-facto reference for new fMRI papers using nipreps tools and atlases such as the Schaefer parcellations, Harvard-Oxford remapped to 2009c, etc.

MNI152NLin6Asym — the older FSL/HCP-style template. Pair this with FSL FEAT, the HCP pipelines, and any atlas distributed in MNI152_T1_2mm space (most FSL atlases, the original Harvard-Oxford).

Pick one and be consistent — atlases, statmaps, and figure overlays must all live in the same space, or you will silently misalign your results.

You can pass multiple spaces to --output-spaces if you genuinely need both (rare for a master’s project).

fmriprep $BIDS_DIR $FMRIPREP_DIR participant \
  --participant-label 001 002 003 \
  --skip-bids-validation \
  --fs-license-file $FS_LICENSE \
  --fs-no-reconall \
  --output-spaces MNI152NLin2009cAsym T1w \
  --nthreads 6 \
  --mem-mb 16000 \
  --work-dir $WORK_DIR \
  --verbose

should you keep FreeSurfer recon-all?

Recon-all takes 8–12 hours per subject and produces full cortical surface reconstructions (white matter / pial surfaces, parcellations, thickness maps). Keep it if you plan surface-based analyses (fsnative or fsaverage output, cortical thickness, surface ROI parcellation). Skip it with --fs-no-reconall if you only need volumetric MNI-space BOLD — your fMRIPrep run will finish in roughly half the time and you trade away the surface outputs.

4.2 Use `Singularity`

If you set up a dedicated Linux server with Singularity installed, you can download the fmriPrep image and run it remotely. Here is a typical code for running fmriprep (assuming you have specified the image location with preimg).

apptainer vs singularity

Apptainer is the community fork of Singularity; the apptainer and singularity CLIs are drop-in compatible for everything we use here. We pass --cleanenv so the host environment (paths, Python configs, locale settings) does not leak into the container — without it your run can pick up irrelevant state and become irreproducible.

# Set these once at top of script
export BIDS_DIR="${BIDS_DIR:?set BIDS dataset root}"
export FMRIPREP_DIR="${FMRIPREP_DIR:-$BIDS_DIR/derivatives/fmriprep}"
export WORK_DIR="${WORK_DIR:?set scratch/work directory}"
export FS_LICENSE="${FS_LICENSE:?set FreeSurfer license path}"
export PROJ_DIR="${PROJ_DIR:-$BIDS_DIR}"             # broader project root, if needed
prepimg="${PREPIMG:?path to fmriprep .simg image}"
 
singularity run --cleanenv \
	--bind $BIDS_DIR \
	--bind $WORK_DIR \
	--bind $PROJ_DIR \
	$prepimg $BIDS_DIR $FMRIPREP_DIR \
	participant \
	--participant-label ${participants_to_run[*]} \
	--skip-bids-validation \
	--fs-license-file $FS_LICENSE \
	--output-spaces MNI152NLin2009cAsym T1w fsnative\
	--bold2anat-init register \
	--bold2anat-dof 12 \
	--fs-no-reconall \
	--force bbr \
	--skull-strip-t1w force \
	--nthreads 56 \
	--omp-nthreads 12 \
	--mem-mb 56000 \
	--stop-on-first-crash \
	--notrack \
	-v \
	-w $WORK_DIR

4.3 Run with Linux cluster `slurm`

Additionally, it is possible to run fMRIPrep using Neurocommand on a Linux cluster. The following is an example of running parallel computing via Linux cluster slurm via LRZ linux cluster.

#!/bin/bash
#SBATCH --job-name=fmriprep
#SBATCH --get-user-env
#SBATCH --clusters=cm4
#SBATCH --partition=cm4_tiny
#SBATCH -t 12:00:00
#SBATCH --nodes=1
#SBATCH --ntasks-per-node=1
#SBATCH --cpus-per-task=32
#SBATCH --mem=32G
#SBATCH --array=01-23%4
#SBATCH --mail-user=your@email
#SBATCH --mail-type=BEGIN,END,FAIL
 
#SBATCH -o logs/fmriprep-%A_%a.log
# Note: SBATCH directives are not shell-expanded, so $PROJ_DIR cannot be used here.
# Either submit `sbatch` from the project root (relative path works) or hard-code an absolute path.
# for linux cluster interactive
 
module load slurm_setup
module use $HOME/spack/modules/x86_avx2/linux-sles15-haswell
module load singularity squashfs
export FMRIPREP_VERSION=24.1.1
module load fmriprep/${FMRIPREP_VERSION}
 
# Print job submission info
echo "Slurm job ID: " $SLURM_JOB_ID
date
 
# Set these once at top of script (or export them before sbatch)
export BIDS_DIR="${BIDS_DIR:-$HOME/studies/Your_Study}"   # BIDS dataset root
export FMRIPREP_DIR="${FMRIPREP_DIR:-$BIDS_DIR/derivatives/fmriprep}"
export WORK_DIR="${WORK_DIR:-$SCRATCH/fmriprep_work}"      # scratch / working dir
export FS_LICENSE="${FS_LICENSE:-$HOME/freesurfer_license.txt}"   # FreeSurfer license
 
mkdir -p "$WORK_DIR" "$FMRIPREP_DIR"
 
export MPLCONFIGDIR=$SCRATCH #matplotlib temp folder
 
SUBJECT=$(printf "%03d" $SLURM_ARRAY_TASK_ID)
 
fmriprep \
	"$BIDS_DIR" "$FMRIPREP_DIR" participant \
	--participant-label "$SUBJECT" \
	--skip-bids-validation \
	--fs-license-file $FS_LICENSE \
	--output-spaces MNI152NLin2009cAsym T1w\
	--fs-no-reconall \
	--nthreads 32 \
	--mem-mb 32000 \
	--stop-on-first-crash \
	-vv \
	-w $WORK_DIR
 
echo "Job $SLURM_JOB_ID finished at $(date)"

Note

For multi-line commands, you need to add \ at the end of each line, and be aware that you should NOT add any blank spaces after \.

5 Check fMRIPrep outputs & confounds

Summary

Goal: decide which nuisance signals to keep (and how many) before denoising.
We’ll walk through the HTML report, inspect the confounds_regressors.tsv, and script our own plots using nilearn.interfaces.fmriprep.load_confounds.

By default, the fMRIPrep will generate output at subfolder /derivatives/fmriprep:

└─ derivatives/fmriprep/
   ├─ logs/
   ├─ dataset_description.json
   ├─ sub-001/
   │  ├─ anat/
   │  ├─ figures/
   │  ├─ func/
   │  └─ log/ 
   ├─ sub-001.html (visual report)
   └─ ...

5.1 Locate the QA material

Each subject has a visual report at
<derivatives>/fmriprep/sub-<ID>.html, plus figures inside sub-<ID>/figures/. oai_citation:0‡fmriprep.org It includes anatomy and functional images reports.

The first step is to scroll to the bottom and check if there are any error reports. Next, verify the brain masks, spatial normalization, and coregistration of functional and anatomical MRI.

Visual Report: Functional Section

This section is most important for fMRI studies. It includes a summary that describes the functional data. The collected confounds are listed for each run.

Brain mask and (anatomical/temporal) CompCor ROIs. Here, aCompCor (magenta contour) and tCompCor (Blue contour pick the top 2% most variable voxels within the brain masks) aim to model physiological and other voxel-wise variance using PCA over CSF/WM masks or high-variance voxels. Additionally, the brain edge (or crown) ROI is marked as a green contour. Verify these contours if any outliers occur. In addition to this, the report’s “Variance explained by a/crown/tCompCor components” panel shows cumulative variance curves for every CompCor mask, showing the number of components that must be included in a model to explain some fraction of variance (50%, 70% or 90%).

The most important subsection is BOLD Summary panel. One example as the below.

FD measures the sum of absolute head-motion derivatives between frames (Power et al., 2012). oai_citation:9‡PMC
DVARS is the root-mean-square signal change across all voxels (frame-to-frame). fMRIPrep reports both raw dvars and standardised std_dvars; spikes with std_dvars > 1.5 are flagged by default. oai_citation:10‡PMC
fMRIPrep marks volumes with FD > 0.5 mm or stdDVARS > 1.5 as motion_outlierXX by default (tune with --fd-spike-threshold, --dvars-spike-threshold). oai_citation:11‡Neurostars

The bottom carpet plot visualize the entire BOLD time series across all voxels as a 2D matrix (time x voxels), enabling rapid assessment of data quality, physiological artifacts, and motion-related spikes. Overlaid confound traces (e.g., Framewise Displacement, DVARS, global signal, WM, CSF) help link visual anomalies to quantitative metrics. By inspecting patterns—such as vertical streaks for sudden motion, horizontal bands for scanner drifts, or crown-region fluctuations—you can decide whether to apply censoring, adjust regressors, or flag problematic runs.

Interpreting Patterns:

Motion Artifacts: Vertical stripes across all rows at a single time point indicate a sudden head-motion event; corroborate with FD spikes
Physiological Noise: Oscillatory horizontal bands within CSF or WM regions reflect cardiac or respiratory cycles; these may persist as rhythmic patterns.
Scanner Drifts: Gradual shifts in baseline intensity across all tissues may indicate scanner instability; appear as sloped color transitions.
Crown Effects: The “crown” rows (outer brain edge) often show artifactual jumps from head or neck movements; flagging crown-specific stripes can isolate edge-based noise

Finally, a heat-map titled “Correlations among nuisance regressors” visualises their pair-wise $r$ plus correlation to GS. oai_citation:3‡fmriprep.org

5.2 Understand what’s stored

All confounds live in
sub-<ID>_task-<task>_run-<run>_desc-confounds_timeseries.tsv. Columns include std_dvars, framewise_displacement, 6 rigid-body parameters, t/a CompCor PCs, global/WM/CSF signals and any motion outliers. oai_citation:4‡fmriprep.org
JSON sidecars add metadata such as CumulativeVarianceExplained for every CompCor component, so you can choose k components that explain (say) 50 % variance. oai_citation:5‡fmriprep.org
fMRIPrep keeps only the PCs needed to reach 50 % by default (--return-all-components overrides). oai_citation:6‡Neurostars oai_citation:7‡Neurostars

Confound columns at a glance

The *_desc-confounds_timeseries.tsv file holds dozens of columns. Here is what the common ones mean and when to reach for them:

Column pattern	What it is	When to use
`trans_x`, `trans_y`, `trans_z`, `rot_x`, `rot_y`, `rot_z`	6 rigid-body motion parameters (mm and radians)	Always include in GLM — bare minimum motion correction
`_derivative1`, `_power2`, `*_derivative1_power2`	Friston-24 extension (temporal derivatives + squared terms)	Use when motion is a concern; stronger artifact suppression at cost of degrees of freedom
`framewise_displacement`	Per-volume scalar of head displacement (Power 2012)	Summary metric — for thresholding/scrubbing, not as a regressor
`dvars`, `std_dvars`	Spatial RMS of temporal difference; `std_dvars` is standardised	Spike detection; default fMRIPrep threshold is `std_dvars > 1.5`
`a_comp_cor_00..NN`	anatomical CompCor PCA components (WM+CSF mask)	Default physiological denoising — typically include first 5–10
`t_comp_cor_00..NN`	temporal CompCor (high-variance voxels)	Alternative when no anatomical mask is reliable
`csf`, `white_matter`, `global_signal`	Mean signal from each tissue mask	Use as nuisance only if you understand the GSR debate; rarely both with aCompCor
`cosine_00..NN`	Discrete cosine basis for built-in high-pass filtering	Include if you skip nilearn/FSL high-pass; otherwise drop
`non_steady_state_outlier_XX`	One-hot regressor flagging non-steady-state initial volumes	Always include — these volumes have unstable T1 saturation
`motion_outlier_XX`	One-hot regressors flagging high-FD or high-DVARS volumes	Scrubbing (volume censoring) — use when retaining the volume is worse than losing one degree of freedom

See 5.2 Confound Selection for principled strategy choices (e.g., the 6HMP + aCompCor + scrubbing combinations recommended by Parkes et al., 2018).

fMRI Tutorials

Explorer

2.3 fmriPrep with Docker

1 · Install Docker

Windows / macOS (Docker Desktop)

2 · Pull & launch Neurodesktop

Add a custom Data Directory

Understand Neurodesktop Modules

3 Code inside the container with VS Code

4. Preprocessing with fMRIPrep

4.1 Using module `fMRIPrep`

4.2 Use `Singularity`

4.3 Run with Linux cluster `slurm`

5 Check fMRIPrep outputs & confounds

5.1 Locate the QA material

Visual Report: Functional Section

5.2 Understand what’s stored

Confound columns at a glance

Graph View

Table of Contents

Backlinks

fMRI Tutorials

Explorer

2.3 fmriPrep with Docker

1 · Install Docker

Windows / macOS (Docker Desktop)

2 · Pull & launch Neurodesktop

Add a custom Data Directory

Understand Neurodesktop Modules

3 Code inside the container with VS Code

4. Preprocessing with fMRIPrep

4.1 Using module fMRIPrep

4.2 Use Singularity

4.3 Run with Linux cluster slurm

5 Check fMRIPrep outputs & confounds

5.1 Locate the QA material

Visual Report: Functional Section

5.2 Understand what’s stored

Confound columns at a glance

Graph View

Table of Contents

Backlinks

4.1 Using module `fMRIPrep`

4.2 Use `Singularity`

4.3 Run with Linux cluster `slurm`