fMRIPrep: passing flags through recon-all process


Is there anyway to pass optional flags to Freesurfer recon-all process inside of the fmriPrep docker image ?

I was thinking of -bigventricles flag for patient with large ventricles.


Not at this moment. But that would be one useful feature to add, would you like to take on it?

I would really like to, but I am a newbie in Python programming and afraid to loose myself in your fmriPrep architecture.

Would it impact many files ?

Would it be useful to define a pull request for passing additional flags to recon-all process of fMRIPrep ?

Just to interject, this is one reason that we allow externally-preprocessed FreeSurfer directories. There are a huge number of options to recon-all, and it’s not really the goal of fMRIPrep to provide an interface to all of them.

One thing that makes something like --recon-flags "-bigventricles" (potentially) problematic is that we would need to know if some flags are best placed alongside -autorecon1, -autorecon2 or -autorecon3. That’s not to say it can’t be done, but it will need to be done carefully, and there’s potential for it to break with the next version of FreeSurfer.

Possibly a simpler approach, if it will work in this case, is to provide an expert file. This would have a pretty high tweakability-to-obtrusiveness ratio.

But again, you can always do your recon-all separately, as long as the subjects are named the same, and the freesurfer/ output directory is in your output directory you specify for fMRIPrep.

1 Like

Thank you for your answer, I understand the constraints.

My aim is to use the anatomical surface pipeline inside of fMRIPrep over Freesurfer directly in order to benefit of the better surfaces created, certainly due to the ANTS skull-stripping.

But my patients are highly atrophied and have big ventricles, and the -bigventricles appeared to greatly improve the surfaces created. So I would like to combine both fMRIPrep and -bigventricles flag to benefit of both.

The expert file seems to be a good solution to specify parameters values but doesn’t apply to -bigventricles flag not attached to one specific command and called uniquely next to recon-all command. Moreover, I don’t see where it is possible in fMRIPrep to pass an expert file ?

Would there be an easy way to pass this flag in fMRIPrep anatomical pipeline once the number of -autorecon is identified ?

Thank you for your answer.

From the help:


If a subject has enlarged ventricles due to atrophy, include the -bigventricles
flag with the -autorecon2 stage in order to prevent surfaces extending into
the ventricle regions. The flag directly affects the binary mri_ca_register,
and mris_make_surfaces indirectly via aseg.presurf.mgz.

Looking at the logic inside recon-all:

set cmd = (mri_ca_register)
if($BigVentricles) set cmd = ($cmd -bigventricles -smoothness 0.5)

So we could either apply it to the -autorecon2-volonly stage, or we could add a way to pass in an expert file and you can pass one that includes:

mri_ca_register -bigventricles -smoothness 0.5

Given that this is a case that can be covered by the expert options, I’m inclined to go that way, so that more cases can be handled without proliferating options. I would add an --fs-expert-file argument to the command line, and then pass that through at the first recon-all call.

Does that seem reasonable?

@effigies that sounds great !

Thanks for your expertise on these commands. I would have however a few little questions:

  1. Why adding -smoothness 0.5 ?
  2. This flag affects mris_make_surfaces indirectly, don’t we need to take this into account ?
  3. According help this flag operates at the -autorecon2 stage so don’t we need to pass the expert file through at the second recon-all call instead of the first ? Don’t we need to pass this expert file from the -autorecon2 and after ?

Many thanks for adding this --fs-expert-file argument !

Because that’s what recon-all adds to the mri_ca_register command when you specify recon-all -bigventricles. See

From reading the source (search for -bigventricles and BigVentricles), no other changes are contingent on -bigventricles. I’m interpreting this as indicating that mris_make_surfaces is operating on the outputs of mri_ca_register.

The expert options file can be passed at any time, and is saved into the FreeSurfer subject directory. It will then have effect at every subsequent call where the options are relevant. For simplicity, it makes sense to inject this file in the first call to recon-all. For sub-millimeter T1w images, we also pass mris_inflate expert options in in the first call, so this is the point it would need to be resolved into a single options file. (FreeSurfer will complain if there already exists an expert options file and you try to pass a new one.)

Are you interested in submitting a pull request? I’d be happy to walk you through the process.

Yes I would be glad to submit a pull request. Ready to follow you through the process.