8  Tutorial Chapter 2: Run fMRIPrep on a single subject

Time: 1-4 hours per subject (FreeSurfer recon-all is the long pole; rerun is much faster). Prereqs: Chapter 1 done, make preflight is green.

This chapter runs the fMRIPrep stage of the pipeline on subject 8 of ds000102. We use sub-08 because that’s the canonical example in Andy’s Brain Book Tutorial #2; if you’ve watched his video you’ll recognize the output.

8.1 1. Sanity preview (no jobs submitted)

DRY_RUN=1 make preprocess BATCH_LABEL=tutorial SUBJECT=sub-08

Expected output ends with:

WOULD SUBMIT: sub-08
sbatch --account=… --partition=… preprocessing/fmri/run_fmriprep_hpc.sh

(On a laptop without SLURM, you’ll see a Docker / Apptainer command instead — no sbatch.)

If the dry-run prints the expected command, you’re ready for the real run.

8.2 2. Real run — local

make preprocess BATCH_LABEL=tutorial SUBJECT=sub-08

What’s happening (in order):

  1. Anatomical processing (≈30-60 min): brain extraction, FreeSurfer recon-all (most of the time), normalization to MNI152NLin2009cAsym.
  2. Field-map preprocessing (≈5 min if fieldmaps present, skipped otherwise — ds000102 has no fieldmaps so SDC is skipped).
  3. BOLD preprocessing per run (≈30-60 min per run): motion correction, slice-time correction, BOLD-to-anat coregistration, resampling to MNI.
  4. Confound time-series extraction: motion params, FD, DVARS, aCompCor, tCompCor, retroicor (if physio).
  5. Report rendering: writes derivatives/fmriprep/sub-08.html.

While this runs, you can:

  • Watch progress: tail -f logs/fmriprep/sub-08.out
  • See SLURM/Docker status: make status (if HPC) or docker ps
  • Walk away — the orchestrator handles everything; the manual --participant-label sub-08 anat/func invocation pattern that Brain Book teaches is wrapped by make preprocess.

8.3 3. Verify outputs

ls data/ds000102/derivatives/fmriprep/sub-08/

Expected:

anat/                         # T1w in MNI, brain mask, GM/WM/CSF probability maps
func/                         # preproc BOLD, brain mask, confound TSV
figures/                      # report figures (PNGs)
log/
ls data/ds000102/derivatives/fmriprep/sub-08/func/

Expected:

sub-08_task-flanker_run-01_space-MNI152NLin2009cAsym_desc-preproc_bold.nii.gz
sub-08_task-flanker_run-01_space-MNI152NLin2009cAsym_desc-brain_mask.nii.gz
sub-08_task-flanker_run-01_desc-confounds_timeseries.tsv
sub-08_task-flanker_run-01_desc-confounds_timeseries.json
…

The _desc-preproc_bold.nii.gz is the input for everything downstream (GLM, ALFF/ReHo/seed-FC, cohort QC).

8.4 4. Validate output completeness automatically

make validate-fmriprep SUBJECT=sub-08

This is the same gate the DAG orchestrator uses before launching the fan-out (mriqc, xcpd, glmsingle, fitlins). It checks: HTML report exists, dataset_description.json exists, expected number of _desc-preproc_bold.nii.gz and _desc-confounds_timeseries.tsv files. Exits non-zero if anything’s missing.

8.5 5. Re-run is fast

If you accidentally re-run make preprocess SUBJECT=sub-08, the sentinel-file check skips fmriprep entirely:

[SKIP] fmriprep: already done (HTML report exists)

To force a full re-run:

rm -rf data/ds000102/derivatives/fmriprep/sub-08
rm -rf data/ds000102/derivatives/freesurfer/sub-08
make preprocess BATCH_LABEL=tutorial SUBJECT=sub-08

8.6 6. Check the run made it into provenance

We auto-write a .provenance.json per run:

cat data/ds000102/derivatives/fmriprep/sub-08/.provenance.json

Expected fields (best-effort; null if unresolved):

{
  "format_version": "1.0",
  "stage": "fmriprep",
  "timestamp_utc": "2026-04-27T19:00:00",
  "host": "your-machine",
  "user": "you",
  "git_commit": "abc12345…",
  "git_dirty": false,
  "config_hash_sha256": "…",
  "container_path": "/path/to/fmriprep_25.2.5.sif",
  "container_digest": "sha256:…",
  "command": "make preprocess BATCH_LABEL=tutorial SUBJECT=sub-08",
  "slurm_job_id": null
}

If you re-run verify_provenance() later (after editing paths.toml or upgrading the container), drift is reported field-by-field. This is the answer to “did anything change since this analysis was last run?”

✅ Chapter 2 complete. Continue to 03_qc_and_inclusion.md for how to read the report + decide which subjects to include.

8.7 What’s different from Andy’s Brain Book Tutorial #2

Brain Book teaches you to assemble the fMRIPrep CLI invocation by hand: which flags to pass, where the FreeSurfer license goes, how to mount Docker volumes. Our make preprocess wraps all of that. The single command does the same work, makes the same Docker/Apptainer mount calls, applies the same FreeSurfer license logic — but it’s canonical and consistent across UCI HPC3, NEU Explorer, your laptop, and any future site preset. When the next fMRIPrep version comes out, you bump FMRIPREP_MODULE in config/site.conf once and every child repo across the lab follows.