Surface pipeline: recon-surf.sh¶

Note

We recommend running the surface pipeline with the standard run_fastsurfer.sh interface!

Overview - recon-surf¶

This directory contains all information needed to run the surface-generation and processing part of FastSurfer. Within approximately 1-1.5 h (depending on processing parallelization and image quality) this pipeline provides a fast FreeSurfer alternative for cortical surface reconstruction, mapping of cortical labels and traditional point-wise and ROI thickness analysis. The basis for the reconstruction pipeline is the accurate anatomical whole brain segmentation following the DKTatlas such as the one provided by the FastSurferCNN or FastSurferVINN deep learning architectures.

The T1-weighted full head input image and the segmentation need to be equivalent in voxel size, dimension and orientation (LIA). With FastSurferCNN or VINN this is always ensured. If the image resolution is below 0.999, the surface pipeline will be run in hires mode.

Also note, that if a file exists at $subjects_dir/$subject_id/mri/orig_nu.mgz, this file will be used as the bias-field corrected image and the bias-field correction is skipped.

Usage¶

The recon_surf directory contains scripts to run the analysis. In addition, a working installation of FreeSurfer (the supported version, usually the most recent) is needed for a native install (or use our Docker/Singularity images).

The main script is called recon-surf.sh which accepts certain arguments via the command line. List them by running the following command:

./recon-surf.sh --help

Required arguments¶

--sd: Output directory $SUBJECTS_DIR (equivalent to FreeSurfer setup –> $SUBJECTS_DIR/sid/mri; $SUBJECTS_DIR/sid/surf … will be created).
--sid: Subject ID for directory inside $SUBJECTS_DIR to be created ($SUBJECTS_DIR/sid/…)

Optional arguments¶

--t1: T1 full head input (not bias corrected). This must be conformed (dimensions: same along each axis, voxel size: isotropic, LIA orientation, and data type UCHAR). Images can be conformed using FastSurferCNN’s conform.py script (usage example: python3 FastSurferCNN/data_loader/conform.py -i <T1_input> -o <conformed_T1_output>). If not passed we use the orig.mgz in the output subject mri directory if available.
--asegdkt_segfile: Global path with filename of segmentation (where and under which name to find it, must already exist). This must be conformed (dimensions: same along each axis, voxel size: isotropic, and LIA orientation). FastSurferCNN’s segmentations are conformed by default. Please ensure that segmentations produced otherwise are also conformed and equivalent in dimension and voxel size to the –t1 image. Default location: $SUBJECTS_DIR/$sid/mri/aparc.DKTatlas+aseg.deep.mgz
--3T: for 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
--fsqsphere: Use FreeSurfer default instead of novel spectral spherical projection for qsphere
--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)
--parallel: Run both hemispheres in parallel
--threads: Set openMP and ITK threads to

Other¶

--py: Command for python, used in both pipelines. Default: python3.10
--no_surfreg: Skip surface registration with FreeSurfer (if only stats are needed)
--fs_license: Path to FreeSurfer license key file. Register at https://surfer.nmr.mgh.harvard.edu/registration.html for free to obtain it if you do not have FreeSurfer installed already

For more details see --help.

Example 1: Surface module inside Docker¶

Docker can be used to simplify the installation (no FreeSurfer on system required). Given you already ran the segmentation pipeline, and want to just run the surface pipeline on top of it (i.e. on a different cluster), the following command can be used:

# 1. Pull the docker image (if it does not exist locally)
docker pull deepmi/fastsurfer:cpu-v?.?.?

# 2. Run command
docker run -v /home/user/my_fastsurfer_analysis:/output \
           -v /home/user/my_fs_license_dir:/fs_license \
           --rm --user $(id -u):$(id -g) deepmi/fastsurfer:cpu-v?.?.? \
           --fs_license /fs_license/license.txt \
           --sid subjectX --sd /output --3T --surf_only

Check Dockerhub to find out the latest release version and replace the “?”.

Docker Flags:

The -v commands mount your output, and directory with the FreeSurfer license file into the Docker container. Inside the container these are visible under the name following the colon (in this case /output and /fs_license).

This essentially calls the run_fastsurfer.sh script as entry point and starts only the surface module. It assumes that this case subjectX exists already and that the output files of the segmentation module are available in the subjectX/mri directory (e.g. /home/user/my_fastsurfeer_analysis/subjectX/mri/aparc.DKTatlas+aseg.deep.mgz, mask.mgz, orig.mgz etc.). The directory will then be populated with the FreeSurfer file structure, including surfaces, statistics and labels file (equivalent to a FreeSurfer recon-all run). It is possible to modify the entry point during the docker call and directly run recon-surf.sh, as we will demonstrate with the Singularity example next.

Example 2: recon-surf inside Singularity¶

Singularity can be used instead of Docker to run the full pipeline or individual modules. In this example we change the entrypoint to recon-surf.sh instead of the standard run_fastsurfer.sh. Usually it is recommended to just use the default, so this is for expert users who may want to try out specific flags that are not passed to the wrapper. Given you already ran the segmentation pipeline, and want to just run the surface pipeline on top of it (i.e. on a different cluster), the following command can be used:

# 1. Build the singularity image (if it does not exist)
singularity build fastsurfer-cpu-v?.?.?.sif docker://deepmi/fastsurfer:cpu-v?.?.?

# 2. Run command
singularity exec --no-home \
                 -B /home/user/my_fastsurfer_analysis:/output \
                 -B /home/user/my_fs_license_dir:/fs_license \
                  ./fastsurfer-cpu-?.?.?.sif \
                  /fastsurfer/recon_surf/recon-surf.sh \
                  --fs_license /fs_license/license.txt \
                  --sid subjectX --sd /output --3T \
                  --t1 <path_to>/subjectX/mri/orig.mgz \
                  --asegdkt_segfile <path_to>/subjectX/mri/aparc.DKTatlas+aseg.deep.mgz

Check Dockerhub to find out the latest release version and replace the “?”.

Singularity Flags:¶

The -B commands mount your output, and directory with the FreeSurfer license file into the Singularity container. Inside the container these are visible under the name following the colon (in this case /data, /output, and /fs_license).
The --no-home command disables the automatic mount of the users home directory (see Best Practice)

The --t1 and --asegdkt_segfile flags point to the already existing conformed T1 input and segmentation from the segmentation module. Also other files from that pipeline will be reused (e.g. the mask.mgz, orig_nu.mgz). The subject directory will then be populated with the FreeSurfer file structure, including surfaces, statistics and labels file (equivalent to a FreeSurfer recon-all run).

Example 3: Native installation - recon-surf on a single subject (subjectX)¶

Given you want to analyze data for subjectX which is stored on your computer under /home/user/my_mri_data/subjectX/orig.mgz, run the following command from the console (do not forget to source FreeSurfer!):

# Source FreeSurfer
export FREESURFER_HOME=/path/to/freesurfer
source $FREESURFER_HOME/SetUpFreeSurfer.sh

# Define data directory
datadir=/home/user/my_mri_data
segdir=/home/user/my_segmentation_data
targetdir=/home/user/my_recon_surf_output  # equivalent to FreeSurfer's SUBJECTS_DIR

# Run recon-surf
./recon-surf.sh --sid subjectX \
                --sd $targetdir \
                --py python3.10 \
                --3T \
                --t1 <path_to>/subjectX/mri/orig.mgz \
                --asegdkt_segfile <path_to>/subjectX/mri/aparc.DKTatlas+aseg.deep.mgz

The --t1 and --asegdkt_segfile flags point to the already existing conformed T1 input and segmentation from the segmentation module. Also other files from that pipeline will be reused (e.g. the mask.mgz, orig_nu.mgz, i.e. under /home/user/my_fastsurfeer_analysis/subjectX/mri/mask.mgz). The subjectX directory will then be populated with the FreeSurfer file structure, including surfaces, statistics and labels file (equivalent to a FreeSurfer recon-all run). The script will generate a bias-field corrected image at /home/user/my_fastsurfeer_analysis/subjectX/mri/orig_nu.mgz, if this did not already exist.

Example 4: recon-surf on multiple subjects¶

Most of the recon_surf functionality can also be achieved by running run_fastsurfer.sh with the --surf_only flag. This means we can also use the brun_fastsurfer.sh command with --surf_only to achieve similar results (see also Example 4.

There are however some small differences to be aware of:

the path to and the filename of the t1 image in the subject_list file is optional.
you are not able to specify a custom, conformed t1 image via --t1 <path> (run_fastsurfer.sh --seg_only will always use $subjects_dir/$subject_id/mri/orig.mgz).

Invoke the following command (make sure you have enough resources to run the given number of subjects in parallel or drop the --parallel_subjects flag to run them in series!):

singularity exec --no-home \
            -B /home/user/my_fastsurfer_analysis:/output \
            -B /home/user/subjects_lists/:/lists \
            -B /home/user/my_fs_license_dir:/fs_license \
            ./fastsurfer.sif \
            /fastsurfer/brun_fastsurfer.sh \
            --surf_only \
            --subjects_list /lists/subjects_list.txt \
            --parallel_subjects \
            --sd /output \
            --fs_license /fs_license/license.txt \
            --3T

A dedicated subfolder will be used for each subject within the target directory. As the --t1 and --asegdkt_segfile flags are not set, a subfolder within the target directory named after each subject ($subject_id) needs to exist and contain T1-weighted conformed image, mask and segmentations (as output by our FastSurfer segmentation networks, i.e. under $subjects_dir/$subject_id/mri/orig.mgz, $subjects_dir/$subject_id/mri/mask.mgz, and $subjects_dir/$subject_id/mri/aparc.DKTatlas+aseg.deep.mgz, respectively). The directory will then be populated with the FreeSurfer file structure, including surfaces, statistics and labels file (equivalent to a FreeSurfer recon-all run). The script will also generate a bias-field corrected image at $subjects_dir/$subject_id/mri/orig_nu.mgz, if this did not already exist.

The logs of individual subject’s processing can be found in $subjects_dir/$subject_id/scripts. On the standard out (e.g. the console), the output from multiple subjects will be interleaved, but each line prepended by the subject id.

Manual Edits¶

Brainmask Edits¶

Currently, FastSurfer has only very limited functionality for manual edits due to missing entrypoints into the recon-surf script. Starting with FastSurfer v2 one frequently requested edit type (brainmask editing) is now possible, as the initial mask is created in the first segmentation stage. By running segmentation and surface processing in two steps, the mask can be edited in-between.

For a Docker setup one can:

Run segmentation only:

docker run --gpus=all --rm --name $CONTAINER_NAME \
                      -v $PATH_TO_IMAGE_DIR:$IMAGE_DIR \
                      -v $PATH_TO_OUTPUT_DIR:$OUTPUT_DIR \
                      --user $UID:$GID deepmi/fastsurfer:gpu-v?.?.? \
                      --t1 $IMAGE_DIR/input.mgz \
                      --sd $OUTPUT_DIR \
                      --sid $SUBJECT_ID \
                      --seg_only

Modify the $PATH_TO_OUTPUT_DIR/$SUBJECT_ID/mri/mask.mgz file as required.

Run the following Docker command to run the surface processing pipeline (remove --3T if you are working with 1.5T data):

docker run --rm --name $CONTAINER_NAME \
           -v $PATH_TO_OUTPUT_DIR:$OUTPUT_DIR \
           -v $PATH_TO_FS_LICENSE_DIR:$FS_LICENSE_DIR \
           --user $UID:$GID deepmi/fastsurfer:gpu-v?.?.? \
           --sid $SUBJECT_ID  \
           --sd $OUTPUT_DIR/$SUBJECT_ID \
           --surf_only --3T \
           --fs_license $FS_LICENSE_DIR/license_file

For a local install you can similarly:

Go to the FastSurfer directory, source FreeSurfer and run the segmentation step:

cd $FASTSURFER_HOME
source $FREESURFER_HOME/SetUpFreeSurfer.sh
./run_fastsurfer.sh --t1 $IMAGE_DIR/input.mgz --sd $OUTPUT_DIR --sid $SUBJECT_ID --seg_only

Modify the $OUTPUT_DIR/$SUBJECT_ID/mri/mask.mgz file.

Run the surface pipeline (remove --3T if you are working with 1.5T data):

./run_fastsurfer.sh --sd $OUTPUT_DIR --sid $SUBJECT_ID --fs_license $FS_LICENSE_DIR/license_file --surf_only --3T

Usage help text¶

$ ./recon_surf/recon-surf.sh --help

Usage: recon-surf.sh --sid <sid> --sd <sdir> --t1 <t1> --asegdkt_segfile <asegdkt_segfile> [OPTIONS]

recon-surf.sh takes a segmentation and T1 full head image and creates surfaces,
thickness etc as a FS subject dir.

FLAGS:
  --sid <subjectID>       Subject ID to create directory inside $SUBJECTS_DIR 
  --sd  <subjects_dir>    Output directory $SUBJECTS_DIR (or pass via env var)
  --t1  <T1_input>        T1 full head input (not bias corrected). This must be
                            a conformed image (dimensions: 256x256x256, voxel
                            size: 1x1x1, LIA orientation, and data type UCHAR).
                            Images can be conformed using FastSurferCNN's
                            conform.py script (usage example: python3
                            FastSurferCNN/data_loader/conform.py -i <T1_input>
                            -o <conformed_T1_output>). Requires an ABSOLUTE Path!
  --asegdkt_segfile <asegdkt_segfile>
                          Name of intermediate DL-based segmentation file
                            (similar to aparc+aseg). This must be conformed
                            (voxel size: isotropic, LIA orientation, and, if voxel
                            size 1mm, dimensions: 256x256x256). FastSurferCNN's
                            segmentations are conformed by default; please ensure
                            that segmentations produced otherwise are conformed.
                            Requires an ABSOLUTE Path! Default location:
                            $SUBJECTS_DIR/$sid/mri/aparc.DKTatlas+aseg.deep.mgz
  --mask_name <mask_file> Path to the brain mask file to use. Default location:
                            $SUBJECTS_DIR/$sid/mri/mask.mgz
  --edits                 Disable the check for existing recon-surf.sh run, replace
                            <asegdkt_segfile> by its manedit-suffixed version,
                            includes wm.mgz and brain.finalsurfs.mgz edits,
                            and enables FreeSurfer-style WM control points.
  --fstess                Revert to FreeSurfer mri_tesselate for surface creation
                            (default: mri_mc)
  --fsqsphere             Revert to FreeSurfer iterative inflation for qsphere
                            (default: spectral spherical projection)
  --fsaparc               Additionally create FS aparc segmentations and ribbon.
                            Skipped by default (--> DL prediction is used which
                            is faster, and usually these mapped ones are fine).
                            Note, if you switch this on it will create all cortical
                            parcellations with FreeSurfer's spherical atlases and
                            also map these into the aparc+aseg file instead of
                            the FastSurfer ones. FastSurfer's cortical DKT atlas
                            results can still be found in:
                            <hemi>.aparc.DKTatlas.mapped.stats
  --3T                    Use the 3T atlas for talairach registration (gives better
                            eTIV estimates for 3T MR images, default: 1.5T atlas).
  --parallel              Run both hemispheres in parallel
  --threads <int>         Set openMP and ITK threads to <int>
  --py <python_cmd>       Command for python, default python3.10
  --fs_license <license>  Path to FreeSurfer license key file. Register at
                            https://surfer.nmr.mgh.harvard.edu/registration.html
                            for free to obtain it if you do not have FreeSurfer
                            installed already.
  --base                  For longitudinal template (base) creation.
  --long <baseid>         For longitudinal time point creation, pass the ID of
                            the base (template) which needs to exist already in
                            the same subjects_dir.
  -h --help               Print Help

Dev Flags:
  --ignore_fs_version     Switch on to avoid check for FreeSurfer version.
                            Program will otherwise terminate if 7.4.1 is 
                            not sourced. Can be used for testing dev versions.
  --no_fs_T1              Do not generate 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            Do not run Surface registration with FreeSurfer (for
                            cross-subject correspondence). Not recommended, but
                            speeds up processing if you just need the stats and
                            don't want to do thickness analysis on the cortex.

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