FastSurfer

[evansorenson]

Hello! Just curious if you had any plans to potentially incorporate FastSurfer into fmriprep as an alternative to freesurfer. My lab is going to be working with large datasets of fMRI data and using FastSurfer would save us a lot of time and computing resources.

Here is the paper for reference if you haven't heard of it: https://www.sciencedirect.com/science/article/pii/S1053811920304985

[effigies]

Hi, thanks for the prod. I did indeed see FastSurfer at OHBM, and had begun to think about how fMRIPrep should work with it.

In the short term, I think we should probably permit users to provide pre-run FastSurfer outputs, as they currently can with pre-run FreeSurfer. If FastSurfer produces outputs that FreeSurfer would detect as complete, then this is trivial. To determine this, or get a sense of how much work is going to need to be done, you can try the following:

from nipype.interfaces import freesurfer as fs

recon = fs.ReconAll(subjects_dir="...",
                    subject_id="...")

print(recon.cmdline)

[evansorenson]

Thanks for the quick response. I was able to run fastsurfer and executed your little script and I got the following as the output:

Traceback (most recent call last):
File "script.py", line 9, in
print(recon.cmdline)
File "/home/esorenson/.local/lib/python3.6/site-packages/nipype/interfaces/freesurfer/preprocess.py", line 1510, in cmdline
[os.path.join(subj_dir, f) for f in infiles],
File "/home/esorenson/.local/lib/python3.6/site-packages/nipype/utils/filemanip.py", line 558, in check_depends
list(map(op.getmtime, deps)) + [0]
File "/home/esorenson/.conda/envs/fast_surf/lib/python3.6/genericpath.py", line 55, in getmtime
return os.stat(filename).st_mtime
FileNotFoundError: [Errno 2] No such file or directory: '/data/backed_up/shared/fMRI_Practice/fastsurfer_es/sub-20190502/mri/aparc+aseg.mgz'

It looks like the the files are named differently in the fastsurfer output compared to the freesurfer files.

[effigies]

Yeah... That's going to make it less drop-in than I'd like.

The way the current set-up works is that you can specify a place to put your FreeSurfer outputs. Then, when we try to run FreeSurfer, it automatically checks for what steps need to be (re-)run based on what outputs are present and whether they are older or newer than their inputs. So we don't have any high-level notion of "The user passed it, so it must be fine"; it's always checked.

FastSurfer is going to either need some alternative way to identify that it's been successfully run, or we'll need a flag where users can say "This is as done as it needs to be."

@mgxd Do you have any thoughts here?

[mgxd]

Yep, unless FastSurfer changes its outputs to follow the same structure of FreeSurfer recon-all (or provides a flag to allow you to do this), this is going to require generating a new FastSurferRecon interface to be used as a drop-in, and handle finding the specific inputs. Then, we'd provide a commandline arg to override FreeSurfer with FastSurfer.

One thing we'll have to keep in mind is altering the boilerplate / citations based on which pipeline was used.

[m-reuter]

Hi, with most files, FastSurfer follows FreeSurfer, but not all. For example, some segmentations results get a new name to distinguish outputs that are more FreeSurfer-like (which can additionally be provided via flags) and outputs that are obtained faster without those additional steps (and usually preferred). Also some files are missing as they are not needed for the FastSurfer pipeline.

[StephDocTUM]

Hi,

I just wanted to ask if there have been any updates in fmriprep to make it compatible with the FastSurfer outputs.

Best,

[m-reuter]

Yes, it would be great to get this sorted out. If we get a list of the FreeSurfer files needed by fmriprep it would be easy to provide those files or provide a lookup which files should be used instead. Currently for example the first thing that is missing is the T1.mgz. We don't use it in FastSurfer but for some reason it is needed in fmriprep. What is strange is that this file is even not needed by FreeSurfer much (it is a specially normalised image and unclear if it should be used for anything outside of FreeSurfer at all). Someone mentioned that it is used to map data between FreeSurfer space and raw input space, but that can be done with any FS file, as this information is contained in the headers. So it is likely that fmriprep does not actually even need the T1.mgz at all and it was chosen only because of the name?

Anyway I am not familiar with fmriprep, but if someone lets us know what we can do to help, would be glad to do that. For example generating the T1.mgz takes only 1-2 minutes longer and could easily be incorporated into FastSurfer or we could just symbolically link to a similar file.

[StephDocTUM]

Yes, this would be absolutely great and speed up amazingly the whole process!

[effigies]

Just to be clear, there are two questions here:

1. What does fMRIPrep need/use?
2. How does fMRIPrep tell when it has a complete reconstruction?

What does fMRIPrep need/use?

surf/:

• ?h.smoothwm
• ?h.pial
• ?h.inflated

From mri/ we need:

• T1.mgz - to calculate any differences between raw T1w and FreeSurfer's space
• brainmask.mgz - for plotting only
• ribbon.mgz - for plotting only
• aseg.mgz - to refine brain mask
• aparc+aseg.mgz

@mgxd @oesteban Can you see anything else we use?

How does fMRIPrep tell when it has a complete reconstruction?

This is more complicated. We break recon-all down into 8 stages:

        $ recon-all -sd <output dir>/freesurfer -subjid sub-<subject_label> \
            -i <bids-root>/sub-<subject_label>/anat/sub-<subject_label>_T1w.nii.gz \
            -T2 <bids-root>/sub-<subject_label>/anat/sub-<subject_label>_T2w.nii.gz \
            -autorecon1 \
            -noskullstrip
        # We inject the ANTs skull-stripped image
        $ recon-all -sd <output dir>/freesurfer -subjid sub-<subject_label> \
            -autorecon2-volonly
        $ recon-all -sd <output dir>/freesurfer -subjid sub-<subject_label> \
            -autorecon-hemi lh -T2pial \
            -noparcstats -noparcstats2 -noparcstats3 -nohyporelabel -nobalabels
        $ recon-all -sd <output dir>/freesurfer -subjid sub-<subject_label> \
            -autorecon-hemi rh -T2pial \
            -noparcstats -noparcstats2 -noparcstats3 -nohyporelabel -nobalabels
        $ recon-all -sd <output dir>/freesurfer -subjid sub-<subject_label> \
            -cortribbon
        $ recon-all -sd <output dir>/freesurfer -subjid sub-<subject_label> \
            -autorecon-hemi lh -nohyporelabel
        $ recon-all -sd <output dir>/freesurfer -subjid sub-<subject_label> \
            -autorecon-hemi rh -nohyporelabel
        $ recon-all -sd <output dir>/freesurfer -subjid sub-<subject_label> \
            -autorecon3

Each of these comes with a list of expected outputs, and flags are added to skip sub-stages if the outputs already exist. If a stage is fully complete, attempting to run it will just echo Nothing to do! (or similar), so it's not directly inspected by fMRIPrep.

I think to do this, we'll need a reliable way to distinguish a FastSurfer directory from a FreeSurfer directory that won't catch incomplete FreeSurfer directories. If we can do that, it should be fairly straightforward to adapt our workflows.

[iabraham]

Just following up whether there have been any updates with regards to this request since nearly a year has passed; and I landed having the exact same thought of swapping in FastSurfer for FreeSurfer in fMRIPrep.

[m-reuter]

@effigies a FastSurfer directory will have /scripts/recon-surf.done in it (if it completed). You can also look for recon-surf.log if it did not complete.
We are creating a T1.mgz for you at the moment, but we renamed some of the outputs to better distinguish them from FreeSurfer stuff and also make clear what atlas is used (e.g. we use DKT): aparc.DKTatlas+aseg.mapped.mgz . The rest should be there.

[mb3152]

@m-reuter @iabraham have either of you tested the new FastSurfer outputs into fmriprep?

[m-reuter]

I have never run fmriprep, but happy to help with information or necessary adjustments.

[iabraham]

@mb3152 I tested the new FastSurfer (cpu version) pulled from Docker via Singularity on a subset of the data here. Its output can be used along with the --fs-subjects-dir flag for fMRIPrep 21.0.2. The only thing that needs to be done to ensure it runs to completion is the creation of an additional mri/aseg.auto_noCCseg.label_intensities.txt file as noted here.