Deep-MI/FastSurfer v2.6.1

on GitHub

FastSurfer 2.6.1 fixes a rare but severe error: since 2.5.0, a region the segmentation mislabels outside the brain
could make the surfaces collapse, without any error. It also fixes the partial volume corrected volumes in some
statistics files; VentricleChoroidVol in brainvol.stats was far too low. For typical subjects, the images and
surfaces are the same as with 2.6.0 or differ only slightly; see "Changes that affect results" for the cases that
change. This release also brings fastsurfer, a launcher that picks, downloads and runs the right FastSurfer image
for your computer with one command, and a quick start built around it.

Are you affected?

Only runs with FastSurfer 2.5.0 to 2.6.0 that include the surfaces, and only if the segmentation network labelled a
region outside the brain as white matter, for example tissue in the neck (#956). Signs:

• white matter peak found at -nan in scripts/recon-surf.log, or
• a cortical volume and thickness far below normal (in #956, 64 instead of 426 mL of cortex).

Every step reports success, so check your runs. Process affected subjects again with 2.6.1 into a new directory.
The surface pipeline now refuses a segmentation from 2.5.0 to 2.6.0 that has this problem, so a --surf_only run
does not fix it.

Highlights

Fix for collapsing surfaces (#956)

Since 2.5.0, aseg.auto.mgz was built from the unmasked network output, so a mislabelled region outside the brain
reached the surface pipeline, where the intensity normalization took it as white matter with intensity 0 (#957).

• The segmentation is cleaned right after the network: labels outside the brain mask are removed and
  disconnected white matter islands are given to their hemisphere. Every output derived from the segmentation
  inherits this, including the volume statistics, which previously counted such regions.
• A warning in the log when more than 1 mL is removed, so such a case is no longer silent.
• The surface pipeline stops if aseg.auto.mgz has any label outside the brain mask it uses, and says what to do.
  This catches --surf_only runs on older segmentations and a mask edited after the segmentation.
• Manual edits: the mask still follows an edited segmentation; labels left outside it are removed with the
  warning, and white matter labels are kept as edited rather than flipped back.

One version per subject (#958)

For identical results, process each subject with exactly one FastSurfer release, and all subjects of a study with
the same major and minor version; the Reproducibility page of the documentation explains this.

• scripts/build.log keeps the history: the version and environment of every run on a subject, each followed by
  its command. Before, each run overwrote it, so only the last run was recorded.
• A run on a subject that another major or minor version processed before stops, and says to process the
  subject again into a new directory. --allow_version_mix continues anyway, and the build log records both
  versions.
• Another patch release, commit or environment continues with a warning, and the build log records both.

The fastsurfer launcher

One command runs FastSurfer on Linux, Windows (WSL2) and macOS, with the flags of run_fastsurfer.sh (#948, #953):

curl -fsSLO https://deep-mi.org/FastSurfer/stable/fastsurfer
chmod +x fastsurfer
./fastsurfer --t1 $HOME/my_mri_data/subjectX/t1_weighted.nii.gz \
    --sid subjectX --sd $HOME/my_fastsurfer_analysis

• Picks the image for your hardware: the CUDA build your NVIDIA GPU and driver support (or the older CUDA 12.6
  image), AMD GPUs with the ROCm image (experimental), or the CPU image, and runs it with Apptainer, Singularity or
  Docker, sharing only the folders the run needs.
• On a Mac with Apple silicon it runs the macOS package natively; ./fastsurfer --update downloads and installs
  it. On Intel Macs it uses Docker.
• Says what is missing instead of failing: no container runtime, Docker not running or not usable by your user,
  Docker Desktop's WSL integration switched off, or the NVIDIA Container Toolkit missing.
• --update downloads the newest release without running it, --update_launcher updates the launcher itself,
  --exec runs other FastSurfer scripts such as brun_fastsurfer.sh and long_fastsurfer.sh, and --print_only
  shows the commands instead of running them. The command reference lists all options.

Documentation

• A new quick start: set up your computer (one tab per system), then the same commands everywhere (#953).
• The installation pages for Linux, Windows and macOS start with the setup and the launcher; Windows users run
  FastSurfer in the WSL terminal.
• The title shows which version a page documents, "FastSurfer 2.6.1" or "FastSurfer dev", and the repeated version
  notes above code blocks are gone (#954).

Changes that affect results

Compared with 2.6.0, results change in these cases:

• Subjects with labels outside the brain mask or disconnected white matter islands (#957): these labels are now
  removed or given to their hemisphere already in the deep segmentation (aparc.DKTatlas+aseg.deep.mgz), so it and
  everything derived from it change, including the aseg+DKT stats. On the test subjects at 0.8 and 1 mm, nothing
  changes. Subjects affected by #956 get correct surfaces.

• Subjects with manual edits (#957): white matter labels are kept as edited instead of being flipped back to the
  other hemisphere, labels left outside the brain mask are removed, and an edited brain mask now also limits
  aseg.auto.mgz.

• Longitudinal processing (--long) (#957): the aseg.auto.mgz of each time point is limited to the template's
  brain mask.

• Statistics files that cover only some structures, for every subject in the default pipeline (#963):

  • brainvol.stats: VentricleChoroidVol increases substantially, BrainSegNotVentSurf decreases by about 0.5 to
    1%.
  • wmparc.DKTatlas.mapped.stats: VentricleChoroidVol as above; the white matter parcels increase by up to about
    2.5%.
  • aseg.presurf.hypos.stats: structure volumes increase by less than 1%.

  aseg.stats, aseg+DKT.stats, the cerebellum and hypothalamus stats, all images and surfaces, and runs with
  --legacy_freesurfer are unchanged. The bug goes back to earlier versions. For existing results, take
  VentricleChoroidVol from aseg.stats; that value was correct.

• Inputs that are conformed except for an oblique orientation (#964): images that already have the conformed data
  type, size and voxel size and LIA axis codes, but a rotated affine. They are now resampled to the exact LIA
  orientation instead of being used as they are, so all their results change. Scanner images are not affected,
  because they are resampled anyway. A subject directory made from such an input by an earlier version stops at the
  input check of the surface pipeline; process it again into a new directory.

• Hypothalamus segmentation (HypVINN) of images with non-isotropic voxels (#968): the segmentation and
  statistics of HypVINN change. Such images reach HypVINN with --keepgeom/--native_image, with --no_biasfield
  (the input T1 is used as it is), or when HypVINN runs on its own. Conformed images, as in the default pipeline, are
  not affected.

• Runs with lesion inpainting (--lesion_mask) use neurolit 0.7.1 (#959, #967). The inpainted image now keeps
  every voxel outside the lesion mask unchanged, so the segmentation and everything after it can change slightly.

Bug fixes

• Surfaces could collapse when the segmentation labelled a region outside the brain (#956, #957), see above.
• VentricleChoroidVol in brainvol.stats was too low in the default (non-legacy) pipeline. brainvol.stats is
  computed without an intensity image, and in that case segstats dropped the interior voxels of each structure and
  counted only the partial volume of its border voxels. VentricleChoroidVol was about 40 to 60% too low.
  wmparc.DKTatlas.mapped.stats imports the value, and BrainSegNotVentSurf is derived from it. Both now agree with
  aseg.stats: VentricleChoroidVol equals the value in aseg.stats, and BrainSegNotVentSurf equals
  BrainSegNotVent. The same bug affected segstats.py without --normfile and mri_segstats.py --pv without
  --i, which under-reported the volume of every structure (#963, by Jignesh Mistry).
• Partial volume corrected volumes no longer depend on which other structures are requested. A voxel can share
  its volume with a structure it touches only at an edge or corner. segstats only counted that share if the voxel's
  own structure was also part of the table. aseg.stats was not affected, because it covers almost all structures.
  Stats files that cover only some structures now count these voxels too: brainvol.stats,
  wmparc.DKTatlas.mapped.stats and aseg.presurf.hypos.stats (#963).
• The orientation check of conform.py was inverted (#964, by Jignesh Mistry). With the default lia, an image
  that was conformed except for an oblique orientation passed the check and was used as it is; with soft-lia, only
  oblique images passed, and exactly LIA images were conformed and rescaled a second time.
• HypVINN used the wrong voxel sizes for non-isotropic images (#968, by Jignesh Mistry). The coronal and
  sagittal views were scaled with the voxel sizes of the wrong axes, so these views were squeezed or stretched, for
  example by about 20% for a sagittally acquired T1 with 1.2 mm slices. Nothing failed visibly. Note that HypVINN
  was trained and evaluated on isotropic images only.
• A uint8 NIfTI input with a scale factor stopped the run (#966, by Clemens Pollak). When float data are saved
  as uint8, nibabel stores a scale factor (scl_slope, scl_inter) instead of clipping, so the image loads as
  scaled floats. FastSurfer took such an image as already conformed and then failed to save it as orig.mgz. It
  is now conformed like any other input.
• Lesion inpainting with neurolit 0.7.1 (#959, #967, by Clemens Pollak):
  • Voxels outside the lesion mask could change slightly, because the image was normalized inconsistently; they
    are now kept as they are.
  • The lesion-aware statistics work with FastSurfer 2.6 and, for submillimeter subjects, use the conformed image that
    matches the segmentation.
  • A failed statistics step now makes lit-postprocessing stop with an error, and the steps that depend on it are
    skipped, instead of reading stale statistics from an earlier run.
  • The backups of files it modifies are kept across reruns, also for symlinked files.
• Running out of GPU memory now stops the run with a hint that fits your settings; before, run_fastsurfer.sh
  continued without a segmentation (#949, by Santiago Estrada).
• tools/build/link_fs.sh handles FreeSurfer paths with spaces (#950, by Jeff) and stops when a link cannot be
  created (#951).
• An import fix in FastSurferCNN/models/optimizer.py (#947).
• The "Potentially Overwriting" warning no longer counts scripts/build.log, and so now appears for the first
  existing file (#958). The issue templates name the build log correctly.

Other changes

• --batch is now --batch_size in run_fastsurfer.sh and long_fastsurfer.sh, the name the Python modules already
  use. --batch still works and prints a deprecation warning (#949).
• The edited brain mask (mri/mask.manedit.mgz) is no longer listed in --help. To change the brain mask, edit the
  segmentation (aparc.DKTatlas+aseg.deep.manedit.mgz), which the mask follows (#958).
• The pipeline test runs nightly again (#946), and tools/compare_subjects.py no longer lists empty directories as
  differences.
• Native installations keep LaPy below 1.8, as the images and the macOS package do: LaPy 1.8 changes the surfaces
  slightly.
• CCMesh.from_contours no longer has the closed and lr_center parameters. Closing the mesh called a LaPy
  function that no longer exists, and FastSurfer never used it (#965, by Clemens Pollak).
• The documentation builds with sphinx-design 0.8 (#969).

Thanks to everyone for their contributions.