FastSurferCNN: segstats.py

segstats.py is a script that is equivalent to FreeSurfer’s mri_segstats. However, it is faster and (automatically) scales very well to multi-processing scenarios.

Full commandline interface of FastSurferCNN/segstats.py

Script to calculate partial volumes and other segmentation statistics of a segmentation file.

usage: python seg_stats.py  -norm <input_norm> -i <input_seg> -o <output_seg_stats> [optional arguments]

Named Arguments

-norm, --normfile

Biasfield-corrected image in the same image space as segmentation (required).

-i, --segfile

Segmentation file to read and use for evaluation (required).

-o, --segstatsfile

Path to output segstats file.

--excludeid

List of segmentation ids (integers) to exclude in analysis, e.g. –excludeid 0 1 10 (default: 0).

Default: [0]

--ids

List of exclusive segmentation ids (integers) to use (default: all ids in –lut or all ids in image).

--merged_label

Add a ‘virtual’ label (first value) that is the combination of all following values, e.g. –merged_label 100 3 4 8 will compute the statistics for label 100 by aggregating labels 3, 4 and 8.

Default: []

--robust

Whether to calculate robust segmentation metrics. This parameter expects the fraction of values to keep, e.g. –robust 0.95 will ignore the 2.5% smallest and the 2.5% largest values in the segmentation when calculating the statistics (default: no robust statistics == –robust 1.0).

Advanced options

--threads

Number of threads to use (defaults to number of hardware threads: 4)

Default: 4

--patch_size

Patch size to use in calculating the partial volumes (default: 32).

Default: 32

--empty

Keep ids for the table that do not exist in the segmentation (default: drop).

Default: False

--device

Select device to run inference on: cpu, or cuda (= Nvidia gpu) or specify a certain gpu (e.g. cuda:1), default: auto

Default: “auto”

--lut

Path and name of LUT to use.

Default: /home/runner/work/FastSurfer/FastSurfer/dev/FastSurferCNN/config/FastSurfer_ColorLUT.tsv

--sid

Optional: directly set the subject id to use. Can be used for single subject input. For multi-subject processing, use remove suffix if sid is not second to last element of input file passed to –t1

--in_dir

Directory in which input volume(s) are located. Optional, if full path is defined for –t1.

--allow_root

Allow execution as root user.

Default: False

--legacy_freesurfer

Reproduce FreeSurfer mri_segstats numbers (default: off). Please note, that exact agreement of numbers cannot be guaranteed, because the condition number of FreeSurfers algorithm (mri_segstats) combined with the fact that mri_segstats uses ‘float’ to measure the partial volume corrected volume. This yields differences of more than 60mm3 or 0.1% in large structures. This uniquely impacts highres images with more voxels (on the boundry) and smaller voxel sizes (volume per voxel).

Default: False

--mixing_coeff

Save the mixing coefficients (default: off).

Default: “”

--alternate_labels

Save the alternate labels (default: off).

Default: “”

--alternate_mixing_coeff

Save the alternate labels’ mixing coefficients (default: off).

Default: “”

--seg_means

Save the segmentation labels’ means (default: off).

Default: “”

--alternate_means

Save the alternate labels’ means (default: off).

Default: “”

--volume_precision

Number of digits after dot in summary stats file (default: 3). Note, –legacy_freesurfer sets this to 1.

Dependencies:

Python 3.8+

Numpy http://www.numpy.org

Nibabel to read images http://nipy.org/nibabel/

Pandas to read/write stats files etc. https://pandas.pydata.org/

Original Author: David Kügler Date: Dec-30-2022 Modified: May-08-2023