Skip to content

fmriprep

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 https://nipoppy.readthedocs.io/.

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!

Objective

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

Procedure

  • Ensure you have the appropriate fMRIPrep container listed in your global_configs.json
  • Use nipoppy/workflow/proc_pipe/fmriprep/run_fmriprep.py 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.

Note

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.

Note

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

Sample cmd: 

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

Note

Unlike DICOM and BIDS run scripts, run_fmriprep.py 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.

Note

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

Note

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