Skip to content


Nipoppy docs are moving

Nipoppy is undergoing a major refactor to move from scripts to a command-line interface (CLI) and Python API. The new documentation website (work in progress) can be found at

If you are using the (soon-to-be legacy) scripts from Nipoppy 0.1.0, this is still the correct place to be. But we encourage you to check out the new website!


Run fMRIPrep pipeline on BIDS-formatted dataset. Note that a standard fMRIPrep run also includes FreeSurfer processing.

Key directories and files

  • <DATASET_ROOT>/bids
  • <DATASET_ROOT>/derivatives/fmriprep/
  • <DATASET_ROOT>/derivatives/freesurfer/
  • bids_filter.json


  • Ensure you have the appropriate fMRIPrep container listed in your global_configs.json
  • Use nipoppy/workflow/proc_pipe/fmriprep/ script to run the fMRIPrep pipeline.
  • You can run "anatomical only" workflow by adding --anat_only flag
  • (Optional) Copy+Rename sample_bids_filter.json to bids_filter.json in the code repo itself. Then edit bids_filter.json to filter certain modalities / acquisitions. This is common when you have multiple T1w acquisitions (e.g. Neuromelanin, SPIR etc.) for a given modality.


When --use_bids_filter flag is set, this bids_filter.json is automatically copied into <DATASET_ROOT>/bids/bids_filter.json to be seen by the Singularity container.

  • For FreeSurfer tasks, you need to have a license.txt file inside <DATASET_ROOT>/derivatives/freesurfer/
  • fMRIPrep manages brain-template spaces using TemplateFlow. These templates can be shared across studies and datasets. Use global_configs.json to specify path to TEMPLATEFLOW_DIR where these templates can reside.


For machines with Internet connections, all required templates are automatically downloaded duing the fMRIPrep run.

Sample cmd:

python nipoppy/workflow/proc_pipe/fmriprep/ \
   --global_config <global_config_file> \
   --participant_id MNI01 \
   --session_id 01 \


Unlike DICOM and BIDS run scripts, can only process 1 participant at a time due to heavy compute requirements of fMRIPrep. For parallel processing on a cluster, sample HPC job scripts (Slurm and SGE) are provided in the hpc subdirectory.


You can change default run parameters in the by looking at the documentation


Clean up working dir (fmriprep_wf): fMRIPrep run generates huge number of intermediate files. You should remove those after successful run to free up space.

fMRIPrep tasks

  • Main MR processing tasks run by fMRIPrep (see fMRIPrep documentation for details):
    • Preprocessing
      • Bias correction / Intensity normalization (N4)
      • Brain extraction (ANTs)
      • Spatial normalization to standard space(s)
    • Anatomical
      • Tissue segmentation (FAST)
      • FreeSurfer recon-all
    • Functional
      • BOLD reference image estimation
      • Head-motion estimation
      • Slice time correction
      • Susceptibility Distortion Correction (SDC)
      • Pre-processed BOLD in native space
      • EPI to T1w registration
      • Resampling BOLD runs onto standard spaces
      • EPI sampled to FreeSurfer surfaces
      • Confounds estimation
      • ICA-AROMA (not run by default)
    • Qualtiy Control