fMRIPrep

NMIND Badge Rating

Overview & Processing

ABCD data were processed through fMRIPrep v25.1.4 pipeline to generate minimally processed derivatives (Esteban et al., 2019). Note that this dataset was generated with a minimal output configuration. Preprocessed BOLD timeseries and confounds are not included. Instructions are provided in the infobox below for users who need to generate the full derivatives set.

Based on the available data, either the structural-only pipeline (using --anat-only) or the full structural and functional pipeline was executed. Only data that passed quality control were included for processing (usable = 1 in the scans.tsv file). Pipeline parameters were set with the following flags (see Usage Notes):

  • --level minimal
    Produce minimal outputs to preserve space
  • --ignore slicetiming
    Ignore slicetiming of input data to prevent unnecessary pipeline failure
  • --random-seed 42
    Sets a fixed random seed for reproducibility
  • --omp-nthreads 1
    Limits OpenMP to a single thread to reduce variability from multi-threading
  • --skull-strip-fixed-seed
    Ensures deterministic skull stripping for reproducibility
  • --fd-spike-threshold .3
    Set motion correction threshold based on frame displacement (FD)
  • --output-spaces MNI152NLin2009cAsym:res-2 fsnative fsLR
    Standard and non-standard spaces to resample anatomical and functional images to
  • --cifti-output 91k
    Output preprocessed BOLD as a CIFTI dense timeseries (with 91k grayordinates, which equates to 2mm resolution)
  • --anat-only
    Used for structural-only processing when functional inputs are absent

The --level minimal flag was used to generate a reduced output set containing only essential preprocessed derivatives (e.g., anatomical derivatives, surfaces, transformations, fieldmaps, and QC reports). Preprocessed BOLD timeseries and confounds are excluded to minimize storage requirements. Full outputs can be generated by re-running fMRIPrep using the minimal derivatives as input via the following steps:

Step 1. Install fMRIPrep

Follow the installation guidelines on the fMRIPrep documentation site here. The remaining steps assume you are using containerized execution via Docker/Singularity as recommended in the documentation.

Step 2. Download and Extract FreeSurfer Derivatives

Download the FreeSurfer derivatives (sourcedata/freesurfer/) if you have not already. These outputs are reused by fMRIPrep in the subsequent step. Extract the derivatives prior to Step 3, for example:

tar -xzf sourcedata/freesurfer/sub-{SUB ID}_ses-{SES ID}.tar.gz -C sourcedata/

Step 3. Run fMRIPrep With Minimal Derivatives

Execute the fMRIPrep container using the parameters specified in the example command below (click to expand infobox). Note that these parameters are the same as described under Pipeline Parameters with the addition of --fs-subjects-dir to specify the location of the input FreeSurfer subjects directory extracted in Step 2.

Replace bracketed placeholders with paths on your system. This command reuses previously generated minimal derivatives to run fMRIPrep efficiently.

singularity run --cleanenv \
  -B {PATH TO RAW BIDS}:/bids_dir \
  -B {PATH TO OUTPUT DIR}:/output_dir \
  -B {PATH TO WORK DIR}:/wd \
  -B {PATH TO FREESURFER LICENSE}:/freesurfer_license.txt \
  {PATH TO FMRIPREP SIF} \
  /bids_dir /output_dir participant \
  --participant-label {SUBJECT_ID} \
  --fs-license-file /freesurfer_license.txt \
  --derivatives minimal={PATH TO EXISTING MINIMAL DERIVATIVES} \
  --ignore slicetiming \
  --fd-spike-threshold 0.3 \
  --random-seed 42 \
  --omp-nthreads 1 \
  --fs-subjects-dir {PATH TO FREESURFER SUBJECTS DIR} \
  --skull-strip-fixed-seed \
  --output-space MNI152NLin2009cAsym:res-2 fsnative fsLR \
  --cifti-output 91k \
  -vv \
  -w /wd

Derivatives

fMRIPrep v25.1.4 derivatives (see Outputs of fMRIPrep) include minimal preprocessing outputs required for quality control and downstream processing.

abcd/
└── derivatives/
    └── abcc-fmriprep_v25.1.4/
        ├── sub-<label>/
        │   ├── figures/
        │   ├── logs/   
        │   └── ses-<label>/
        │       ├── anat/
        │       ├── fmap/
        │       └── func/
        │
        ├── sourcedata/
        │   └── freesurfer/
        │       └── sub-<label>_ses-<label>.tar.gz  # FreeSurfer outputs
        │
        └── sub-<label>_ses-<label>.html  # QC report (executive summary)
TipAT A GLANCE
  • Anatomical derivatives
    Preprocessed T1w/T2w images, brain masks, and tissue segmentations (CSF, GM, WM)
  • Surface derivatives
    Cortical meshes (pial, white, midthickness), sulcal depth, thickness maps, and registration spheres (fsaverage, fsLR)
  • Transformations
    Spatial transforms between native, MNI152NLin2009cAsym, MNI152NLin6Asym, FreeSurfer native, and fsLR spaces
  • Functional reference data
    Motion-corrected, coregistered BOLD reference images, with associated brain masks and transforms
  • Fieldmaps
    Distortion correction fieldmaps (coefficient-based, EPI-based, and preprocessed)
  • Quality control
    HTML reports and SVG visualizations

Structural Outputs

The anat/ directory contains preprocessed anatomical images, brain masks, segmentations, surface reconstructions, and spatial transforms.

anat/

# Preprocessed T1w and T2w images in native space
  ├── *_desc-preproc_<T1w/T2w>.nii.gz
  
# Linear and nonlinear transforms between T1w, fsnative, and MNI152 spaces
  ├── *_from-MNI152NLin2009cAsym_to-T1w_mode-image_xfm.h5
  ├── *_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5
  ├── *_from-MNI152NLin6Asym_to-T1w_mode-image_xfm.h5
  ├── *_from-T1w_to-MNI152NLin6Asym_mode-image_xfm.h5
  ├── *_from-T1w_to-fsnative_mode-image_xfm.txt
  ├── *_from-fsnative_to-T1w_mode-image_xfm.txt
  ├── *_from-orig_to-T1w_mode-image_xfm.txt
  
# White, pial, and midthickness cortical surface reconstructions
  ├── *_hemi-{L|R}_{pial|white|midthickness}.surf.gii
  
# Spherical registrations to fsLR, fsaverage, and MSM-Sulc-aligned spaces
  ├── *_hemi-{L|R}_sphere.surf.gii
  ├── *_hemi-{L|R}_space-fsLR_desc-{reg|msmsulc}_sphere.surf.gii
  ├── *_hemi-{L|R}_space-fsaverage_desc-reg_sphere.surf.gii 
  
# Surface metrics: vertex-wise cortical sulcal depth & thickness
  ├── *_hemi-{L|R}_{sulc|thickness}.shape.gii
  
# Tissue probability maps (GM, WM, CSF) and discrete segmentation
  ├── *_label-<GM/WM/CSF>_probseg.nii.gz
  ├── *_dseg.nii.gz
  
# Brain mask and cortical ribbon mask
  ├── *_desc-brain_mask.nii.gz
  └── *_desc-ribbon_mask.nii.gz

Functional Outputs

The func/ directory contains reference images and transforms only for each task (mid, rest, sst, nback). Preprocessed BOLD timeseries and confounds are not included in this minimal output set.

func/

# Motion-corrected and coregistered BOLD reference images
  ├── *_task-<task>_run-*_desc-hmc_boldref.nii.gz
  ├── *_task-<task>_run-*_desc-coreg_boldref.nii.gz
  
# Motion correction and coregistration transforms (BOLD ↔ T1w, pepolar)
  ├── *_task-<task>_run-*_from-orig_to-boldref_mode-image_desc-hmc_xfm.txt
  ├── *_task-<task>_run-*_from-boldref_to-T1w_mode-image_desc-coreg_xfm.txt
  ├── *_task-<task>_run-*_from-boldref_to-pepolarfunc-AP_mode-image_xfm.txt
  ├── *_task-<task>_run-*_from-boldref_to-pepolarfunc-PA_mode-image_xfm.txt
  
# Brain mask in BOLD reference space
  └── *_task-<task>_run-*_desc-brain_mask.nii.gz

Fieldmap Outputs

The fmap/ directory contains fieldmaps used for susceptibility distortion correction.

fmap/

# Preprocessed pepolar fieldmap (Hz) and metadata
  ├── *_acq-func_run-*_fmapid-pepolarfunc-<label>_desc-preproc_fieldmap.nii.gz
  ├── *_acq-func_run-*_fmapid-pepolarfunc-<label>_desc-preproc_fieldmap.json
  
# Fieldmap coefficients for interpolation
  ├── *_acq-func_run-*_fmapid-pepolarfunc-<label>_desc-coeff_fieldmap.nii.gz
  
# EPI-based fieldmap reference image
  └── *_acq-func_run-*_fmapid-pepolarfunc-<label>_desc-epi_fieldmap.nii.gz

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. (2019). Nature Methods, 16(1), 111–116. https://doi.org/10.1038/s41592-018-0235-4