Brain mask generation in fmriprep


First off, thank you for the fantastic software! I recently applied fmriprep (version: 23.2.0) via the singularity container (version: 3.11.1), on a list of subjects, using the following command:

singularity run -B $FREESURFER_HOME \\
               $fmriprep \\
               $bids_dir $output_dir participant \\
               --fs-license-file $FREESURFER_HOME/license.txt \\
               --fs-subjects-dir $output_dir/sourcedata/freesurfer \\
               --participant-label $subj \\
               --force-no-bbr \\
               --use-syn-sdc \\
               --skip-bids-validation \\
               --output-spaces anat MNI152NLin2009cAsym:res-2 \\
               --stop-on-first-crash \\
               -w $work_dir

Overall, it worked exactly as hoped, with one caveat: the brain mask generated after the susceptibility distortion step (green contour in the pic below) appeared severely constricted:

It also seems that this constricted brain mask (red contour in the pic below) was used for the subsequent CompCor analysis, potentially limiting the identification of nuisance regressors (magenta and blue ROIs):

Interestingly, I also ran the same script as above, but without the fieldmap-less correction flag (–use-syn-sdc), and the identified brain mask used for the CompCor analysis appeared to be accurate:

I would still prefer to use the fieldmap-less correction, if possible, since it led to slightly better co-registrations between the EPIs and T1w, and was thus wondering what you would recommend the next steps be:

  1. Is the constricted brain mask generated by --use-syn-sdc expected, given that the areas that were excluded displayed some levels of signal dropout/increased susceptibility distortion artifact (from what I can tell from the figures above)?

  2. Would it be ok to manually fix the brain mask, by let’s say resampling the anatomical brain mask (anat/sub*_ses*_space-MNI152NLin2009cAsym_desc-brain_mask.nii.gz) into func/ sub*_ses*_task-*_space-MNI152NLin2009cAsym_desc-preproc_bold.nii.gz space, as previously suggested (fMRIprep BOLD brain mask issue - #12 by jsein)? If I did this step though, how could I have fmriprep run all subsequent steps (including CompCor) with the correct mask—should I just replace the brain mask in the working dir and rerun fmriprep?

  3. Or should I replace the brain mask as described in (2) after fmriprep has run, and just use the “correct” mask for all future postprocessing steps, without re-running fmriprep?

Thank you very much in advance!



Hi @pfotiad, and welcome to neurostars!

I think syn-sdc has been known to be buggy in this version (e.g., fieldmap-less SDC in v. 23.2.0a2 producing odd/distorted results · Issue #3158 · nipreps/fmriprep · GitHub). You could try rolling back to 23.1.4 and see if that helps (or even 20.2.7, the latest Long Term Support series release). You might also try running without --force-no-bbr flag.

Unrelated, but I also recommend running singularity with additional -e --containall --writable-tmpfs flags, in general.


Thank you so much, @Steven, for your extremely prompt response! I’ll go ahead and use 23.1.4 (with and without --force-no-bbr) and let you know how it goes (will also add the extra flags you mentioned)!


Hi @pfotiad,

Sounds good, keep us updated!

Something like this might work, by using the new --levels argument of fMRIPrep in 23.2.0, which facilitates using precomputed derivatives. I think @effigies would be the authority on that though.

I suppose that would work if you do not want to use aCompCor, but I think going for a more stable and permanent fix would be preferred.


Here the thing to do would be to run with --level minimal, fix up the mask manually, and then pass the first round of derivatives to a new run with --derivatives outputs/round1 (or whatever you choose to name that output).

Thank you, @effigies ! While I’m comparing across the proposed methodologies, I wanted to follow up on the --level approach:

I run fmriprep (essentially same command as above) with “–level minimal” and I got the following outputs under the anat dir:

fmap dir:

and func dir:

I then added the (not yet generated by --level minimal) *MNI152NLin2009cAsym_res-2_desc-brain_mask.nii.gz and *_space-T1w_desc-brain_mask.nii.gz that I wanted into the func directory, and re-run fmriprep after removing the --level flag and adding the derivatives flag:

–derivatives $output_dir

The results were unfortunately the same as without running the level/derivatives combo. So my two questions are:

  1. Is my running process correct or should I be running these two flags in a different fashion? and

  2. Assuming that my process is not correct (which I believe is the most likely scenario), which of the output files from --level minimal (i.e., from the screenshots above) would I need to fix manually to fix the constricted green contour shown in my first figure above. Or is it a file that is stored in the working directory?

Thanks again!

Only replacing something we generate will have an effect. So if the anatomical mask is bad, replace sub-05/anat/sub-05_desc-brain_mask.nii.gz. If the BOLD-T1w coregistration went wrong, replace sub-05/func/sub-05_task-rest_from-boldref_to-T1w_mode-image_desc-coreg_xfm.txt.

Thanks, @effigies. So I replaced ‘sub-05/func/sub-05_task-rest_from-boldref_to-T1w_mode-image_desc-coreg_xfm.txt’ with the txt file that I wanted right after running fmriprep with the --level minimal flag, and then re-ran fmriprep with the –derivatives flag and without changing anything else. The resulting ‘sub-05/func/sub-05_task-rest_from-boldref_to-T1w_mode-image_desc-coreg_xfm.txt’ was different than the one I input (and also different from the original one that was generated with --level minimal). The way that I am using the -derivatives flag is as such:

--derivatives $output_dir/$subj/ses-01/anat \
--derivatives $output_dir/$subj/ses-01/fmap \
--derivatives $output_dir/$subj/ses-01/func \

(I’ve used different variations as well, such as:

--derivatives $output_dir/$subj \

but the results were the same.)

  1. Is the resulting ‘sub-05/func/sub-05_task-rest_from-boldref_to-T1w_mode-image_desc-coreg_xfm.txt’ expected to change after re-running with the -derivatives flag? I was under the impression that it should stay the same.

  2. Also, do you happen to know which file is being read to generate the green contour shown in my top figure above in my original post, found under ‘alignment between the anatomical reference of the fieldmap and the target EPI’? (as this appears to be the culprit)

Thanks again in advance for your time!

Just wanted to re-circulate this message!

Thanks again,

Hmm. We should probably raise an error if people don’t pass a derivative dataset. You should just be passing --derivatives $output_dir.

That said, I also don’t think it’s a great idea to write into one of your input directories, as you are then trusting the tool not to overwrite your inputs. I generally organize data into:

    [current output]

So something like:


From preprocessing, you would use:

fmriprep sourcedata/raw . participant --derivatives sourcedata/overrides [args]

Sounds great, thanks @effigies!