Manual Edits¶

We have noticed that FastSurfer segmentations and surface results are very robust and rarely require any manual edits. However, for your convenience, we allow manual edits in various stages of the FastSurfer pipeline to fix errors or inaccuracies in FastSurfer results. These editing options include approaches that are inherited from FreeSurfer as well as some FastSurfer-specific editing options.

The provided editing options may be changed or extended in the future, also depending on requests from the community. Furthermore, we invite users to contribute such changes and/or datasets of paired MRI images and edited files to improve FastSurfer’s neural networks.

What are Edits?¶

Edits are manual interventions into the pipeline that change intermediate results. By “editing” intermediate results, later steps operate on updated information. While rarely necessary, some errors of the pipeline (see below) can be addressed and the quality of results can be improved.

What can be edited?¶

Edits primarily affect FastSurfer’s surface pipeline but some edits exist also during the segmentation steps. To understand how edits affect different results and how to perform them, it is important to understand the order of processing steps in FastSurfer.

Pipeline overview¶

The FastSurfer pipeline comprises segmentation modules and the surface module.

The outputs of the relevant modules are:

The asegdkt module:
- as the primary output: the whole brain segmentation (default name: <subject_dir>/mri/aparc.DKTatlas+aseg.deep.mgz)
- as secondary outputs from the whole brain segmentation:
  - the aseg without CC segmentation (<subject_dir>/mri/aseg.auto_noCCseg.mgz) and
  - the brainmask (<subject_dir>/mri/mask.mgz).
The biasfield module uses the white matter segmentation (from aseg) and computes:
- a bias field-corrected version of the conformed input image (<subject_dir>/mri/orig_nu.mgz) and
- optionally may also perform a Talairach registration (<subject_dir>/mri/transforms/talairach.(xfm|lta)).
Other segmentation modules (e.g. the hypothalamus segmentation) use the biasfield corrected image as input.
The surface module (recon-surf) generates surfaces and stats files based on outputs from the asegdkt module, including:
1. a Talairach registration (<subject_dir>/mri/transforms/talairach.(xfm|lta)), if not already performed before,
2. the WM segmentation (<subject_dir>/mri/wm.mgz) and filled version (<subject_dir>/mri/filled.mgz) to initialize surfaces and
3. a brainmask (<subject_dir>/mri/brain.finalsurfs.mgz) to guide the positioning of the pial surfaces.

Possible Edits¶

FastSurfer supports the following edits:

Bias field corrected inputs (for improved image quality, not really an edit)
asegdkt_segfile: <subject_dir>/mri/aparc.DKTatlas+aseg.deep.mgz via <subject_dir>/mri/aparc.DKTatlas+aseg.deep.manedit.mgz
Talairach registration: <subject_dir>/mri/transforms/talairach.xfm (overwrites automatic results from <subject_dir>/mri/transforms/talairach.auto.xfm)
White matter segmentation: <subject_dir>/mri/wm.mgz and <subject_dir>/mri/filled.mgz
Pial placement: <subject_dir>/mri/brain.finalsurfs.mgz via <subject_dir>/mri/brain.finalsurfs.manedit.mgz

Note, as FastSurfer’s surface pipeline is derived from FreeSurfer, some edit options and corresponding naming schemes are inherited from FreeSurfer.

General process¶

Most editing options require that you have processed the case and you are able to access and modify the files in that image’s directory, i.e. <subject_dir>. Based on a quality inspection of results, segmentations and surfaces, one of the edits (see above) is chosen and performed. Then, the case is re-processed using the --edits flag, i.e. run_fastsurfer.sh is re-run (same FastSurfer command and FastSurfer version as before, but add --edits). Finally, you would check in another quality inspection, if the quality issues are resolved.

For example (including the setup for native processing, see Examples for other processing options):

# Setup FASTSURFER and FREESURFER
export FASTSURFER_HOME=/path/to/fastsurfer
export FREESURFER_HOME=/path/to/freesurfer
source $FREESURFER_HOME/SetUpFreeSurfer.sh

# Define data directory
export SUBJECTS_DIR=/home/user/my_fastsurfer_analysis

# Run FastSurfer
$FASTSURFER_HOME/run_fastsurfer.sh \
    --sd $SUBJECTS_DIR --sid case_with_edits \
    --t1 $SUBJECTS_DIR/case_with_edits/mri/orig/001.mgz \
    --fs_license $FREESURFER_HOME/.license \
    --edits # more flags as needed, e.g. --parallel --3T --threads 4

Note, a re-run of the segmentation pipeline, as in the command above, should not be harmful, but is only required if the asegdkt_segfile was edited. Therefore, in most cases, we can skip the segmentation step with

# Setup FASTSURFER and FREESURFER ... (see above)

# Run FastSurfer
$FASTSURFER_HOME/run_fastsurfer.sh \
    --sd $SUBJECTS_DIR --sid case_with_edits \
    --t1 $SUBJECTS_DIR/case_with_edits/mri/orig/001.mgz \
    --fs_license $FREESURFER_HOME/.license \
    --edits --surf_only # more flags as needed, e.g. --parallel --3T --threads 4

Bias field correction¶

This edit is “outside” of the FastSurfer pipeline and not really an edit.

When to use¶

The asegdkt module failed or produced unreliable segmentation maps, especially if bias fields are very strong as for example for 7T images. This can be detected by inspecting <subject_dir>/mri/aparc.DKTatlas+aseg.deep.mgz, <subject_dir>/mri/aseg.auto_noCCseg.mgz and <subject_dir>/mri/mask.mgz.

What to do¶

Perform bias field correction prior to segmentation (FastSurfer) and provide the bias corrected image as input. Sometimes, even FastSurfer’s own bias field correction can help, which can be found in <subject_dir>/mri/orig_nu.mgz. Alternatively, external bias field correction tools may help (e.g. bias_correct from SPM). Run FastSurfer as a new run on this new input file.

For example:

Step 1: Run FastSurfer to obtain a bias field corrected image (not needed if you already processed with FastSurfer a first time):

# Setup FASTSURFER and FREESURFER ... (see above)

# Run FastSurfer
$FASTSURFER_HOME/run_fastsurfer.sh \
    --sd $SUBJECTS_DIR --sid case_bias_only \
    --t1 /path/to/the/original/T1.mgz \
    --seg_only --no_hypothal --no_cereb --threads 16

Step 2: Run FastSurfer again, but this time input the bias field corrected image (i.e. orig_nu.mgz) instead of original input image. The file orig_nu.mgz can be found in the output directory under the mri subfolder. The output produced from the second iteration should be saved in a different output directory for comparative analysis with the output produced in first iteration.
```
# Setup FASTSURFER and FREESURFER ... (see above)

# Run FastSurfer
$FASTSURFER_HOME/run_fastsurfer.sh \
    --sd $SUBJECTS_DIR --sid case_bias_corrected \
    --t1 $SUBJECTS_DIR/case_bias_only/mri/orig_nu.mgz \
    --fs_license $FREESURFER_HOME/.license # more flags as needed, e.g. --parallel --3T --threads 4
```

Step 3: Compare and check if bias field correction fixed the issues:

freeview $SUBJECTS_DIR/case_bias_only/mri/orig_nu.mgz $SUBJECTS_DIR/case_bias_corrected/mri/aparc.DKTatlas+aseg.deep.mgz $SUBJECTS_DIR/case_bias_only/mri/orig_nu.mgz $SUBJECTS_DIR/case_bias_corrected/mri/aparc.DKTatlas+aseg.deep.mgz

asegdkt_segfile¶

When to use¶

(Minor) Segmentation errors such as over- and under-segmentation, of the gray and white matter, but also subcortical structures. In particular, over- and under-segmentation of the brainmask, gray matter over segmentation into the dura, white matter undersegmentation in the cortex (causing missed gyri or cortical thickness overestimation). In specific, such errors are inspected in <subject_dir>/mri/aparc.DKTatlas+aseg.deep.mgz, <subject_dir>/mri/aseg.auto_noCCseg.mgz and <subject_dir>/mri/mask.mgz.

What to do¶

Copy the file <subject_dir>/mri/aparc.DKTatlas+aseg.deep.mgz to the same directory and name it <subject_dir>/mri/aparc.DKTatlas+aseg.deep.manedit.mgz.
Open <subject_dir>/mri/aparc.DKTatlas+aseg.deep.manedit.mgz (for example using Freeview) and resolve all errors/quality issues.
Re-run FastSurfer to propagate the changes into other results. Among others, this updates <subject_dir>/mri/aseg.auto_noCCseg.mgz and <subject_dir>/mri/mask.mgz.

Talairach registration¶

When to use¶

The estimated total intracranial volume is inaccurate.

What to do¶

Copy <subject_dir>/mri/transforms/talairach.auto.xfm to <subject_dir>/mri/transforms/talairach.xfm, replace the symlink that is already there.
Edit <subject_dir>/mri/transforms/talairach.xfm to have the intended talairach matrix, see the FreeSurfer tutorial for details.
Re-run FastSurfer to update the eTIV value in all stats files.

White matter segmentation¶

When to use¶

Over- and/or under-segmentation of the white matter: voxels that should be white matter are excluded, or those that should not are included.

What to do¶

Often, these errors should be fixed by asegdkt_segfile <subject_dir>/mri/aparc.DKTatlas+aseg.deep.manedit.mgz, but if that is not successful:

Open and edit <subject_dir>/mri/wm.mgz and/or <subject_dir>/mri/filled.mgz.
Re-run FastSurfer to propagate the edits.

The manual label 255 indicates a voxel should be included in the white matter and a voxel labeled 1 should not.

Pial surface placement¶

When to use¶

Over- and/or under-segmentation of the cortical gray matter: voxels that should be gray matter are excluded, or those that should not are included.

What to do¶

Often, these errors should be fixed in asegdkt_segfile <subject_dir>/mri/aparc.DKTatlas+aseg.deep.manedit.mgz, but if that is not successful:

Open end edit <subject_dir>/mri/brain.finalsurfs.manedit.mgz (overwriting values in <subject_dir>/mri/brain.finalsurfs.mgz).
Re-run FastSurfer to fix the pial surface. The manual label 255 indicates a voxel should be included in the gray matter and a voxel labeled 1 should not.

Side effects of edits¶

Technically, all edits are changes to the processing pipeline and may cause systematic effects in the analysis. Computational edits (e.g. Bias Field Correction) should be integrated for all cases of an analysis. Other effects are impossible to avoid (edit carefully), often very small and hard to account for. It is recommended to analyze whether files with edits distort results in a specific direction, i.e. how do effect sizes change if manually edited cases are excluded?

Guide for experienced FreeSurfer users¶

The following list enumerates editing options available in FreeSurfer and how to achieve similar edits in FastSurfer.

Skull stripping by editing <subject_dir>/mri/brainmask.mgz (delta to brainmask.auto.mgz) -> asegdkt_segfile
Talairach registration by editing <subject_dir>/mri/transforms/talairach.xfm (delta to transforms/talairach.xfm) -> Talairach Registration
Brain extraction by editing <subject_dir>/mri/brain.mgz (delta to brain.auto.mgz) -> asegdkt_segfile
Subcortical segmentation: <subject_dir>/mri/aseg.presurf.mgz (delta to aseg.presurf.auto.mgz) -> asegdkt_segfile
CRS seeds: PONS, CC, LH, RH, watershed => seed files (<subject_dir>/scripts/seed-(pons|cc|lh|rh|ws).crs.man.dat) -> asegdkt_segfile
WM control points: <subject_dir>/tmp/control.dat -> asegdkt_segfile
In-file edits of the white matter segmentation: <subject_dir>/mri/wm.mgz (delta to wm.auto.mgz) -> asegdkt_segfile or White Matter Segmentation (wm.mgz)
In-file edits of the filled Fill white matter segmentation: <subject_dir>/mri/filled.mgz (delta to filled.auto.mgz) -> asegdkt_segfile or White Matter Segmentation (filled.mgz)
Pial placement correction: <subject_dir>/mri/brain.finalsurfs.manedit.mgz (delta to brain.finalsurfs.mgz) -> Pial Surface Placement

What NOT to do¶

Do not edit the following files. These edits may not work as you expect and are considered undefined behavior.

The mask: <subject_dir>/mri/mask.mgz
The brainmask: <subject_dir>/mri/brainmask.mgz
WM control points: <subject_dir>/tmp/control.dat
Seed points: <subject_dir>/scripts/seed-(pons|cc|lh|rh|ws).crs.man.dat
The downstream subcortical segmentation: <subject_dir>/mri/aseg.presurf.mgz

We hope that this will help with (some of) your editing needs. Thanks for using FastSurfer.