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 segstats.py (-norm|-pv) <input_norm> -i <input_seg> -o <output_seg_stats> [optional arguments] [{measures,mri_segstats} ...]

Named Arguments¶

--pvfile, -pv

Path to image used to compute the partial volume effects (default: the file passed as normfile). This file is required, either directly or indirectly via normfile.

-norm, --normfile

Path to biasfield-corrected image (the same image space as segmentation). This file is used to calculate intensity values. Also, if no pvfile is defined, it is used as pvfile. One of normfile or pvfile is 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: None).

Default: []

--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).

--measure_only

Only calculate the Measures in the header, no PV table.

Default: False

Suboptions¶

subparser: Possible choices: measures

Advanced options (not shown in -h)¶

--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'

--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

--sd

Directory in which evaluation results should be written. Will be created if it does not exist. Optional if full path is defined for –pred_name.

--lut

Path and name of LUT to use.

--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 boundary) 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). Use 1 for maximum FreeSurfer compatibility).

Default: 3

--norm_name

Option to change the name of the in volume (default: norm).

Default: 'norm'

--norm_unit

Option to change the unit of the in volume (default: MR).

Default: 'MR'

Sub-commands¶

measures¶

Options to configure measures

python segstats.py (...) measures [optional arguments]

Named Arguments¶

--compute

Additional Measures to compute based on imported/computed measures:<br>Cortex, CerebralWhiteMatter, SubCortGray, TotalGray, BrainSegVol-to-eTIV, MaskVol-to-eTIV, SurfaceHoles, EstimatedTotalIntraCranialVol

Default: []

--import

Additional Measures to import from the measurefile.<br>Example measures (‘all’ to import all measures in the measurefile):<br>BrainSeg, BrainSegNotVent, SupraTentorial, SupraTentorialNotVent, SubCortGray, lhCortex, rhCortex, Cortex, TotalGray, lhCerebralWhiteMatter, rhCerebralWhiteMatter, CerebralWhiteMatter, Mask, SupraTentorialNotVentVox, BrainSegNotVentSurf, VentricleChoroidVol, BrainSegVol-to-eTIV, MaskVol-to-eTIV, lhSurfaceHoles, rhSurfaceHoles, SurfaceHoles, EstimatedTotalIntraCranialVol<br>Note, ‘all’ will always be overwritten by any explicitly mentioned measures.

Default: []

--file

Default file to read measures (–import …) from. If the path is relative, it is interpreted as relative to subjects_dir/subject_id from–sd and –subject_id.

Default: brainvol.stats

--from_seg

Replace the default segfile to compute measures from by -i/–segfile. This will default to ‘mri/aseg.mgz’ for –legacy_freesurfer and to the value of -i/–segfile otherwise.

Dependencies:

Python 3.10

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: Dec-07-2023

Revision: 1.1