fsqc toolbox

Description

This package provides quality assurance / quality control scripts for FastSurfer- or FreeSurfer-processed structural MRI data. It will check outputs of these two software packages by means of quantitative and visual summaries. Prior processing of data using either FastSurfer or FreeSurfer is required, i.e. the software cannot be used on raw images.

It is a revision, extension, and translation to the Python language of the Freesurfer QA Tools. It has been augmented by additional functions from the MRIQC toolbox, and with code derived from the LaPy and BrainPrint toolboxes.

This page provides general, usage, and installation information. See here for the full documentation.

Functionality
Development
Usage
Installation
Requirements
Known issues
Authors
Citations
License

Functionality

The core functionality of this toolbox is to compute the following features:

variable | description ---------------|---------------------------------------------------------------- subject | subject ID wm_snr_orig | signal-to-noise ratio for white matter in orig.mgz gm_snr_orig | signal-to-noise ratio for gray matter in orig.mgz wm_snr_norm | signal-to-noise ratio for white matter in norm.mgz gm_snr_norm | signal-to-noise ratio for gray matter in norm.mgz cc_size | relative size of the corpus callosum lh_holes | number of holes in the left hemisphere rh_holes | number of holes in the right hemisphere lh_defects | number of defects in the left hemisphere rh_defects | number of defects in the right hemisphere topo_lh | topological fixing time for the left hemisphere topo_rh | topological fixing time for the right hemisphere con_lh_snr | wm/gm contrast signal-to-noise ratio in the left hemisphere con_rh_snr | wm/gm contrast signal-to-noise ratio in the right hemisphere rot_tal_x | rotation component of the Talairach transform around the x axis rot_tal_y | rotation component of the Talairach transform around the y axis rot_tal_z | rotation component of the Talairach transform around the z axis

The program will use an existing output directory (or try to create it) and write a csv table into that location. The csv table will contain the above metrics plus a subject identifier.

The program can also be run on images that were processed with FastSurfer (v1.1 or later) instead of FreeSurfer. In that case, simply add a --fastsurfer switch to your shell command. Note that FastSurfer's full processing stream must have been run, including surface reconstruction (i.e. brain segmentation alone is not sufficient).

In addition to the core functionality of the toolbox there are several optional modules that can be run according to need:

screenshots module

This module allows for the automated generation of cross-sections of the brain that are overlaid with the anatomical segmentations (asegs) and the white and pial surfaces. These images will be saved to the 'screenshots' subdirectory that will be created within the output directory. These images can be used for quickly glimpsing through the processing results. Note that no display manager is required for this module, i.e. it can be run on a remote server, for example.

surfaces module

This module allows for the automated generation of surface renderings of the left and right pial and inflated surfaces, overlaid with the aparc annotation. These images will be saved to the 'surfaces' subdirectory that will be created within the output directory. These images can be used for quickly glimpsing through the processing results. Note that no display manager is required for this module, i.e. it can be run on a remote server, for example.

skullstrip module

This module allows for the automated generation cross-sections of the brain that are overlaid with the colored and semi-transparent brainmask. This allows to check the quality of the skullstripping in FreeSurfer. The resulting images will be saved to the 'skullstrip' subdirectory that will be created within the output directory.

fornix module

This is a module to assess potential issues with the segmentation of the corpus callosum, which may incorrectly include parts of the fornix. To assess segmentation quality, a screenshot of the contours of the corpus callosum segmentation overlaid on the norm.mgz will be saved as 'cc.png' for each subject within the 'fornix' subdirectory of the output directory.

modules for the amygdala, hippocampus, and hypothalamus

These modules evaluate potential missegmentations of the amygdala, hippocampus, and hypothalamus. To assess segmentation quality, screenshots will be created These modules require prior processing of the MR images with FreeSurfer's dedicated toolboxes for the segmentation of the amygdala and hippocampus, and the hypothalamus, respectively.

shape module

The shape module will run a shapeDNA / brainprint analysis to compute distances of shape descriptors between lateralized brain structures. This can be used to identify discrepancies and irregularities between pairs of corresponding structures. The results will be included in the main csv table, and the output directory will also contain a 'brainprint' subdirectory.

outlier module

This is a module to detect extreme values among the subcortical ('aseg') segmentations as well as the cortical parcellations. If present, hypothalamic and hippocampal subsegmentations will also be included.

The outlier detection is based on comparisons with the distributions of the sample as well as normative values taken from the literature (see References).

For comparisons with the sample distributions, extreme values are defined in two ways: nonparametrically, i.e. values that are 1.5 times the interquartile range below or above the 25th or 75th percentile of the sample, respectively, and parametrically, i.e. values that are more than 2 standard deviations above or below the sample mean. Note that a minimum of 10 supplied subjects is required for running these analyses, otherwise NaNs will be returned.

For comparisons with the normative values, lower and upper bounds are computed from the 95% prediction intervals of the regression models given in Potvin et al., 2016, and values exceeding these bounds will be flagged. As an alternative, users may specify their own normative values by using the '--outlier-table' argument. This requires a custom csv table with headers label, upper, and lower, where label indicates a column of anatomical names. It can be a subset and the order is arbitrary, but naming must exactly match the nomenclature of the 'aseg.stats' and/or '[lr]h.aparc.stats' file. If cortical parcellations are included in the outlier table for a comparison with aparc.stats values, the labels must have a 'lh.' or 'rh.' prefix. upper and lower are user-specified upper and lower bounds.

The main csv table will be appended with the following summary variables, and more detailed output about will be saved as csv tables in the 'outliers' subdirectory of the main output directory.

variable | description -------------------------|--------------------------------------------------- n_outliers_sample_nonpar | number of structures that are 1.5 times the IQR above/below the 75th/25th percentile n_outliers_sample_param | number of structures that are 2 SD above/below the mean n_outliers_norms | number of structures exceeding the upper and lower bounds of the normative values

Development

Current status

We are happy to announce the release of version 2.0 of the fsqc toolbox. With this release comes a change of the project name from qatools to fsqc, to reflect increased independence from the original FreeSurfer QA tools, and applicability to other neuroimaging analysis packages - such as Fastsurfer.

Recent changes include the addition of the hippocampus and hypothalamus modules as well as the addition of surface and skullstrip visualization modules. Technical changes include how the package is installed, imported, and run, see below for details.

A list of changes is available here.

Main and development branches

This repository contains multiple branches, reflecting the ongoing development of the toolbox. The two primary branches are the main branch (stable) and the development branch (dev). New features will first be added to the development branch, and eventually be merged with the main branch.

Roadmap

The goal of the fsqc project is to create a modular and extensible software package that provides quantitative metrics and visual information for the quality control of FreeSurfer- or Fastsurfer-processed MR images. The package is currently under development, and new features are continuously added.

New features will initially be available in the development branch of this toolbox and will be included in the [main branch](ht

Fsqc

Install / Use

README