README.md

Welcome to FastSurfer!

Overview

This README contains all information needed to run FastSurfer - a fast and accurate deep-learning based neuroimaging pipeline. FastSurfer provides a fully compatible FreeSurfer alternative for volumetric analysis (within minutes) and surface-based thickness analysis (within only around 1h run time). FastSurfer is transitioning to sub-millimeter resolution support throughout the pipeline.

The FastSurfer pipeline consists of two main parts for segmentation and surface reconstruction.

• the segmentation sub-pipeline (seg) employs advanced deep learning networks for fast, accurate segmentation and volumetric calculation of the whole brain and selected substructures.
• the surface sub-pipeline (recon-surf) reconstructs cortical surfaces, maps cortical labels and performs a traditional point-wise and ROI thickness analysis.

Segmentation Modules

• approximately 5 minutes (GPU), --seg_only only runs this part.

Modules (all run by default):

1. asegdkt: FastSurferVINN for whole brain segmentation (deactivate with --no_asegdkt)
   • the core, outputs anatomical segmentation and cortical parcellation and statistics of 95 classes, mimics FreeSurfer’s DKTatlas.
   • requires a T1w image (notes on input images), supports high-res (up to 0.7mm, experimental beyond that).
   • performs bias-field correction and calculates volume statistics corrected for partial volume effects (skipped if --no_biasfield is passed).
2. cereb: CerebNet for cerebellum sub-segmentation (deactivate with --no_cereb)
   • requires asegdkt_segfile, outputs cerebellar sub-segmentation with detailed WM/GM delineation.
   • requires a T1w image (notes on input images), which will be resampled to 1mm isotropic images (no native high-res support).
   • calculates volume statistics corrected for partial volume effects (skipped if --no_biasfield is passed).
3. hypothal: HypVINN for hypothalamus subsegmentation (deactivate with --no_hypothal)
   • outputs a hypothalamic subsegmentation including 3rd ventricle, c. mammilare, fornix and optic tracts.
   • a T1w image is highly recommended (notes on input images), supports high-res (up to 0.7mm, but experimental beyond that).
   • allows the additional passing of a T2w image with --t2 <path>, which will be registered to the T1w image (see --reg_mode option).
   • calculates volume statistics corrected for partial volume effects based on the T1w image (skipped if --no_bias_field is passed).

Surface reconstruction

• approximately 60-90 minutes, --surf_only runs only the surface part.
• supports high-resolution images (up to 0.7mm, experimental beyond that).

Requirements to input images

All pipeline parts and modules require good quality MRI images, preferably from a 3T MR scanner. FastSurfer expects a similar image quality as FreeSurfer, so what works with FreeSurfer should also work with FastSurfer. Notwithstanding module-specific limitations, resolution should be between 1mm and 0.7mm isotropic (slice thickness should not exceed 1.5mm). Preferred sequence is Siemens MPRAGE or multi-echo MPRAGE. GE SPGR should also work. See --vox_size flag for high-res behaviour.

Getting started

Installation

There are two ways to run FastSurfer (links are to installation instructions):

1. In a container (Singularity or Docker) (OS: Linux, Windows, MacOS on Intel),
2. As a native install (all OS for segmentation part).

We recommended you use Singularity or Docker on a Linux host system with a GPU. The images we provide on DockerHub conveniently include everything needed for FastSurfer. You will also need a FreeSurfer license file for the Surface pipeline. We have detailed per-OS Installation instructions in the INSTALL.md file.

Usage

All installation methods use the run_fastsurfer.sh call interface (replace *fastsurfer-flags* with FastSurfer flags), which is the general starting point for FastSurfer. However, there are different ways to call this script depending on the installation, which we explain here:

1. For container installations, you need to define the hardware and mount the folders with the input (/data) and output data (/output):
   (a) For singularity, the syntax is

   singularity exec --nv \
                    --no-home \
                    -B /home/user/my_mri_data:/data \
                    -B /home/user/my_fastsurfer_analysis:/output \
                    -B /home/user/my_fs_license_dir:/fs_license \
                    ./fastsurfer-gpu.sif \
                    /fastsurfer/run_fastsurfer.sh 
                    *fastsurfer-flags*
   

   The --nv flag is needed to allow FastSurfer to run on the GPU (otherwise FastSurfer will run on the CPU).

   The --no-home flag tells singularity to not mount the home directory (see Singularity documentation for more info).

   The -B flag is used to tell singularity, which folders FastSurfer can read and write to.

   See also Example 2 for a full singularity FastSurfer run command and the Singularity documentation for details on more singularity flags.

   (b) For docker, the syntax is

   docker run --gpus all \
              -v /home/user/my_mri_data:/data \
              -v /home/user/my_fastsurfer_analysis:/output \
              -v /home/user/my_fs_license_dir:/fs_license \
              --rm --user $(id -u):$(id -g) \
              deepmi/fastsurfer:latest \
              *fastsurfer-flags*
   

   The --gpus flag is needed to allow FastSurfer to run on the GPU (otherwise FastSurfer will run on the CPU).

   The -v flag is used to tell docker, which folders FastSurfer can read and write to.

   See also Example 1 for a full FastSurfer run inside a Docker container and the Docker documentation for more details on the docker flags including --rm and --user.

2. For a native install, you need to activate your FastSurfer environment (e.g. conda activate fastsurfer_gpu) and make sure you have added the FastSurfer path to your PYTHONPATH variable, e.g. export PYTHONPATH=$(pwd).

   You will then be able to run fastsurfer with ./run_fastsurfer.sh *fastsurfer-flags*.

   See also Example 3 for an illustration of the commands to run the entire FastSurfer pipeline (FastSurferCNN + recon-surf) natively.

FastSurfer_Flags

Please refer to FASTSURFER_FLAGS.

Examples

All the examples can be found here: FASTSURFER_EXAMPLES

• Example 1: FastSurfer Docker
• Example 2: FastSurfer Singularity
• Example 3: Native FastSurfer on subjectX with parallel processing of hemis
• Example 4: FastSurfer on multiple subjects
• Example 5: Quick Segmentation
• Example 6: Running FastSurfer on a SLURM cluster via Singularity

Output files

Modules output can be found here: FastSurfer_Output_Files

• Segmentation module
• Cerebnet module
• Surface module

System Requirements

Recommendation: At least 8 GB system memory and 8 GB NVIDIA graphics memory --viewagg_device gpu

Minimum: 7 GB system memory and 2 GB graphics memory --viewagg_device cpu --vox_size 1

Minimum CPU-only: 8 GB system memory (much slower, not recommended) --device cpu --vox_size 1

Minimum Requirements:

	--viewagg_device	Min GPU (in GB)	Min CPU (in GB)
1mm	gpu	5	5
1mm	cpu	2	7
0.8mm	gpu	8	6
0.8mm	cpu	3	9
0.7mm	gpu	8	6
0.7mm	cpu	3	9

Expert usage

Individual modules and the surface pipeline can be run independently of the full pipeline script documented in this documentation. This is documented in READMEs in subfolders, for example: whole brain segmentation only with FastSurferVINN, cerebellum sub-segmentation, hypothalamic sub-segmentation and surface pipeline only (recon-surf).

Specifically, the segmentation modules feature options for optimized parallelization of batch processing.

FreeSurfer Downstream Modules

FreeSurfer provides several Add-on modules for downstream processing, such as subfield segmentation ( hippocampus/amygdala, brainstem, thalamus and hypothalamus ) as well as TRACULA. We now provide symlinks to the required files, as FastSurfer creates them with a different name (e.g. using "mapped" or "DKT" to make clear that these file are from our segmentation using the DKT Atlas protocol, and mapped to the surface). Most subfield segmentations require wmparc.mgz and work very well with FastSurfer, so feel free to run those pipelines after FastSurfer. TRACULA requires aparc+aseg.mgz which we now link, but have not tested if it works, given that DKT-atlas merged a few labels. You should source FreeSurfer 7.3.2 to run these modules.

Intended Use

This software can be used to compute statistics from an MR image for research purposes. Estimates can be used to aggregate population data, compare groups etc. The data should not be used for clinical decision support in individual cases and, therefore, does not benefit the individual patient. Be aware that for a single image, produced results may be unreliable (e.g. due to head motion, imaging artefacts, processing errors etc). We always recommend to perform visual quality checks on your data, as also your MR-sequence may differ from the ones that we tested. No contributor shall be liable to any damages, see also our software LICENSE.

References

If you use this for research publications, please cite:

Henschel L, Conjeti S, Estrada S, Diers K, Fischl B, Reuter M, FastSurfer - A fast and accurate deep learning based neuroimaging pipeline, NeuroImage 219 (2020), 117012. https://doi.org/10.1016/j.neuroimage.2020.117012

Henschel L*, Kuegler D*, Reuter M. (*co-first). FastSurferVINN: Building Resolution-Independence into Deep Learning Segmentation Methods - A Solution for HighRes Brain MRI. NeuroImage 251 (2022), 118933. http://dx.doi.org/10.1016/j.neuroimage.2022.118933

Faber J*, Kuegler D*, Bahrami E*, et al. (*co-first). CerebNet: A fast and reliable deep-learning pipeline for detailed cerebellum sub-segmentation. NeuroImage 264 (2022), 119703. https://doi.org/10.1016/j.neuroimage.2022.119703

Estrada S, Kuegler D, Bahrami E, Xu P, Mousa D, Breteler MMB, Aziz NA, Reuter M. FastSurfer-HypVINN: Automated sub-segmentation of the hypothalamus and adjacent structures on high-resolutional brain MRI. Imaging Neuroscience 2023; 1 1–32. https://doi.org/10.1162/imag_a_00034

Stay tuned for updates and follow us on X/Twitter.

Acknowledgements

This project is partially funded by:

• Chan Zuckerberg Initiative
• German Federal Ministry of Education and Research

The recon-surf pipeline is largely based on FreeSurfer.