Skip to content

RUN_FASTSURFER.md

Latest commit

 

History

History
88 lines (75 loc) · 10.7 KB

RUN_FASTSURFER.md

File metadata and controls

88 lines (75 loc) · 10.7 KB
Raw

run_fastsurfer.sh

Next, you will learn how to specify the <fastsurfer_flags> by replacing <fastsurfer_flags> with your specific options. run_fastsurfer.sh is the central command of FastSurfer. In general, run_fastsurfer.sh is called once for each T1w MRI image that is to be processed and each call will result in one "Subject Folder" with segmentation maps, surfaces and statistics tables. If you want to process multiple images, you can either loop through the images yourself or use brun_fastsurfer.sh or srun_fastsurfer.sh, which are multi-subject extensions to run_fastsurfer.sh.

On this page, we explain FastSurfer's options, usually referred to as <fastsurfer_flags> in this documentation. The <fastsurfer_flags> will usually at least include the subject directory (--sd), the subject name/id (--sid) and the path to the input image (--t1). For example:

export FASTSURFER_HOME=${FASTSURFER_HOME:-/path/to/FastSurfer}
$FASTSURFER_HOME/run_fastsurfer.sh --sd $HOME/my_fastsurfer_analysis \
    --sid subjectX --t1 $HOME/my_mri_data/subjectX/t1_weighted.nii.gz --3T

Additionally, you can use --seg_only or --surf_only to only run a part of the pipeline or --no_biasfield, --no_cereb, --no_hypothal, --no_cc, and --no_asegdkt to switch off individual segmentation modules. Here, we have also added the --3T flag, which tells FastSurfer to register against the 3T atlas which is only relevant for the ICV estimation (eTIV).

In the following, we give an overview of the most important options. You can view a full list of options with

export FASTSURFER_HOME=${FASTSURFER_HOME:-/path/to/FastSurfer}
$FASTSURFER_HOME/run_fastsurfer.sh --help

Required arguments

  • --sd: Output directory $SUBJECTS_DIR (equivalent to FreeSurfer setup --> $SUBJECTS_DIR/<subject_id>/mri; $SUBJECTS_DIR/<subject_id>/surf ... will be created).
  • --sid: Subject ID for directory inside $SUBJECTS_DIR to be created ($SUBJECTS_DIR/<subject_id>/...)
  • --t1: T1 full head input (does not need to be bias corrected, global path). The network was trained with conformed images (UCHAR, cubic volume, 0.7mm - 1mm voxels and standard slice orientation; typically 256x256x256 at 1mm and larger cubes for higher-resolution isotropic inputs). These specifications are checked in the run_prediction.py script and the image is automatically conformed if it does not comply. By default, outputs are written in the FastSurfer conform space used for segmentation, which closely follows FreeSurfer conforming in mri_convert -c. The --keepgeom path is the exception: it uses an internal soft-LIA reordering for the 2D networks and maps results back to native geometry before writing outputs.

Conditionally required

Required for Docker when running surface module:

  • --fs_license: Path to FreeSurfer license key file (needed for the surface module and, if activated, the talairach registration --tal_reg in the segmentation). For local installs, your local FreeSurfer license will automatically be detected (usually $FREESURFER_HOME/license.txt or $FREESURFER_HOME/.license). Use this flag if autodetection fails or if you use Docker with the surface module. To get a license, register (for free).

Optional arguments

Segmentation pipeline arguments

  • --seg_only: Only run the brain segmentation pipeline and skip the surface pipeline.
  • --seg_log: Name and location for the log-file for the segmentation. Default: $SUBJECTS_DIR/<subject_id>/scripts/deep-seg.log
  • --viewagg_device: Define where the view aggregation should be run on. Can be "auto" or a device (see --device). By default, the program checks if you have enough memory to run the view aggregation on the GPU. The total memory is considered for this decision. If this fails, or you actively specify "cpu" view aggregation is run on the CPU. Equivalently, if you pass a different device, view aggregation will be run on that device (no memory check will be done).
  • --device: Select device for neural network segmentation (auto, cpu, cuda, cuda:<device_num>, mps), where cuda means NVIDIA GPU, you can select which one e.g. "cuda:1". Default: "auto", check GPU and then CPU. "mps" is the Apple silicon GPU of a Mac (macOS package or native installation), which "auto" picks there.
  • --asegdkt_segfile: Name of the segmentation file, which includes the aparc+DKTatlas-aseg segmentations. Requires an ABSOLUTE Path! Default location: $SUBJECTS_DIR/<subject_id>/mri/aparc.DKTatlas+aseg.deep.mgz
  • --no_cereb: Switch off the cerebellum sub-segmentation.
  • --no_hypothal: Skip the hypothalamus segmentation.
  • --no_cc: Skip the segmentation and analysis of the corpus callosum.
  • --lesion_mask <lesion_mask_path>: Path to a binary lesion mask in the same space as the T1 input. If provided, FastSurfer will wrap the segmentation and surface pipelines with lesion inpainting using LIT. This feature is useful for images with tumors or other large lesions; review LIT-modified outputs before downstream use.
  • --cereb_segfile: Name of the cerebellum segmentation file. Requires an ABSOLUTE Path! Default location: $SUBJECTS_DIR/<subject_id>/mri/cerebellum.CerebNet.nii.gz
  • --no_biasfield: Deactivate the biasfield correction and calculation of partial volume-corrected statistics in the segmentation modules. HypVINN does run but expects that biasfields are corrected externally.
  • --native_image or --keepgeom: Only supported for --seg_only. Preserve the native image geometry (orientation, image size, and voxel size) for saved outputs. Internally, FastSurfer may temporarily reorder/flip the image to a soft-LIA layout so the 2D networks still see the expected plane ordering, but written outputs stay in native geometry; only intensity scaling and dtype conversion are applied as needed. This also includes experimental support for anisotropic images (no extreme anisotropy).

Surface pipeline arguments

  • --surf_only: Only run the surface pipeline. The segmentation created by FastSurferVINN must already exist in this case.
  • --3T: Only affects Talairach registration: use the 3T atlas instead of the 1.5T atlas (which is used if the flag is not provided). This gives better (more consistent with FreeSurfer) ICV estimates (eTIV) for 3T and better Talairach registration matrices, but has little impact on standard volume or surface stats.
  • --fstess: Use mri_tesselate instead of marching cube (default) for surface creation (not recommended, but more similar to FreeSurfer)
  • --fsqsphere: Use FreeSurfer default instead of novel spectral spherical projection for qsphere (also not recommended)
  • --fsaparc: Use FS aparc segmentations in addition to DL prediction (slower in this case and usually the mapped ones from the DL prediction are fine)
  • --no_fs_T1: Skip generation of T1.mgz (normalized nu.mgz included in standard FreeSurfer output) and create brainmask.mgz directly from norm.mgz instead. Saves 1:30 min.
  • --no_surfreg: Skip the surface registration (which creates sphere.reg) to safe time. Note, sphere.reg will be needed for any cross-subject statistical analysis of thickness maps, so do not use this option if you plan to perform cross-subject analysis.

Some other flags

  • --threads, --threads_seg and --threads_surf: Target number of threads for all modules, segmentation, and surface pipeline: a number, auto or max. Without these flags, an exported OMP_NUM_THREADS sets the budget for both pipelines, and otherwise auto applies: inside a cgroup CPU quota (such as docker run --cpus) or a scheduler job (Slurm, SGE, PBS, LSF) the allocated CPUs, and otherwise the physical cores less one, which stays free for other work. On Apple silicon the efficiency cores stay free instead, so auto uses all performance cores. Either way auto uses at most 4 threads for a segmentation on a GPU, where only the steps around the networks run on the CPU, and at most 8 otherwise, beyond which more threads gain little. For surfaces it uses at least 2 where the CPUs allow, so that the two hemispheres run at the same time. max uses all available CPUs. OMP_THREAD_LIMIT caps the budget in every case. For surfaces the value is a total budget: with 2 or more the two hemispheres run at the same time and split it, so 2 gives one thread each and 8 gives four each. --parallel runs the hemispheres at the same time with one thread each even at --threads 1, which keeps every binary single threaded while still using two cores; above 1 it has no effect. The topology correction always runs single-threaded regardless, because its result depends on the processing order (see Reproducibility). FastSurfer exports the budget to every library's own thread variable (OMP_NUM_THREADS, OPENBLAS_NUM_THREADS, MKL_NUM_THREADS, VECLIB_MAXIMUM_THREADS, ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS), so that numpy's BLAS follows it too. A library variable that you exported with a lower value is kept as a ceiling for that library. The log of each pipeline states the budget and where it came from.
  • --vox_size: Forces processing at a specific voxel size. If a number between 0.7 and 1 is specified (below is experimental) the T1w image is conformed to that isotropic voxel size and processed. If "min" is specified (default), the voxel size is read from the size of the minimal voxel size (smallest per-direction voxel size) in the T1w image: If the minimal voxel size is bigger than 0.98mm, the image is conformed to 1mm isotropic. If the minimal voxel size is smaller or equal to 0.98mm, the T1w image will be conformed to isotropic voxels of that voxel size. The voxel size (whether set manually or derived) determines whether the surfaces are processed with highres options (below 1mm) or not.
  • --py: Command for python, used in both pipelines. Default: python3 -s (-s keeps packages in your home directory out)
  • --conformed_name: Name of the file in which the conformed input image will be saved. Default location: $SUBJECTS_DIR/<subject_id>/mri/orig.mgz
  • -h, --help: Prints help text

Reproducibility

Which results stay identical between two runs, how the thread count and the machine affect them, and how to compare two runs is described in Reproducibility.

Troubleshooting

run_fastsurfer.sh calls python3 by default. If python3 is not the python version your FastSurfer environment was set up with, pass that one with --py, for example --py python{{ PYTHON_VERSION }}.

Full list of flags

:cwd: /../