This is a set of quality assurance / quality control scripts for Freesurfer processed structural MRI data.
It is a revision, extension, and translation to the Python language of the Freesurfer QA Tools that are provided at https://surfer.nmr.mgh.harvard.edu/fswiki/QATools
It has been augmented by additional functions from the MRIQC toolbox, available at https://github.com/poldracklab/mriqc and https://osf.io/haf97, and with code derived from the shapeDNA and brainPrint toolboxes, available at https://reuter.mit.edu.
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
instead of FreeSurfer. In that case, simply add a --fastsurfer switch to your
shell command. Note that the full processing stream FastSurfer 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.
- fornix module
This is a module to assess potential issues with the segementation 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.
- shape module
The shape module will run a shapeDNA / braiprint 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. 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., 1996, 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' file. 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 |
python3 qatools.py --subjects_dir <directory> --output_dir <directory>
[--subjects SubjectID [SubjectID ...]]
[--subjects-file <file>] [--screenshots]
[--screenshots-html] [--fornix] [--fornix-html]
[--shape] [--outlier] [--fastsurfer] [-h]
required arguments:
--subjects_dir <directory>
subjects directory with a set of Freesurfer 6.0 processed
individual datasets.
--output_dir <directory>
output directory
optional arguments:
--subjects SubjectID [SubjectID ...]
list of subject IDs
--subjects-file <file> filename of a file with subject IDs (one per line)
--screenshots create screenshots
--screenshots-html create html summary page of screenshots (requires
--screenshots)
--fornix check fornix segmentation
--fornix-html create html summary page of fornix evaluation (requires
--fornix)
--shape run shape analysis
--outlier run outlier detection
--outlier-table specify normative values (only in conjunction with
--outlier)
--fastsurfer use FastSurfer instead of FreeSurfer output
getting help:
-h, --help display this help message and exit
-
Run the QC pipeline for all subjects found in
/my/subjects/directory:python3 /my/scripts/directory/qatools.py --subjects_dir /my/subjects/directory --output_dir /my/output/directory -
Run the QC pipeline for two specific subjects that need to present in
/my/subjects/directory:python3 /my/scripts/directory/qatools.py --subjects_dir /my/subjects/directory --output_dir /my/output/directory --subjects mySubjectID1 mySubjectID2 -
Run the QC pipeline for all subjects found in
/my/subjects/directoryafter full FastSurfer processing:python3 /my/scripts/directory/qatools.py --subjects_dir /my/subjects/directory --output_dir /my/output/directory --fastsurfer -
Run the QC pipeline plus the screenshots module for all subjects found in
/my/subjects/directory:python3 /my/scripts/directory/qatools.py --subjects_dir /my/subjects/directory --output_dir /my/output/directory --screenshots -
Run the QC pipeline plus the fornix pipeline for all subjects found in
/my/subjects/directory:python3 /my/scripts/directory/qatools.py --subjects_dir /my/subjects/directory --output_dir /my/output/directory --fornix -
Run the QC pipeline plus the shape analysis pipeline for all subjects found in
/my/subjects/directory:python3 /my/scripts/directory/qatools.py --subjects_dir /my/subjects/directory --output_dir /my/output/directory --shape -
Run the QC pipeline plus the outlier detection module for all subjects found in
/my/subjects/directory:python3 /my/scripts/directory/qatools.py --subjects_dir /my/subjects/directory --output_dir /my/output/directory --outlier -
Run the QC pipeline plus the outlier detection module with a user-specific table of normative values for all subjects found in
/my/subjects/directory:python3 /my/scripts/directory/qatools.py --subjects_dir /my/subjects/directory --output_dir /my/output/directory --outlier --outlier-table /my/table/with/normative/values.csv -
Note that the
--screenshots,--fornix,--shape, and--outlierarguments can also be used in conjunction.
This software can be downloaded from its github repository at https://github.com/Deep-MI/qatools-python.
Alternatively, it can be cloned directly from its repository via git clone https://github.com/Deep-MI/qatools-python.
The qatools.py script will then be executable from the command line, as
detailed above.
Optional packages (if running the shape analysis module) include the brainprint-python
and lapy packages from . They can be installed using
pip3 install --user git+https://github.com/Deep-MI/BrainPrint-python.git
and pip3 install --user git+https://github.com/Deep-MI/LaPy.git. They should
both be version 0.2 or newer.
As an alternative to their command-line usage, the qc scripts can also be run within a pure python environment, i.e. installed and imported as a python package.
Use the following code to download, build and install a package from its github repository into your local python package directory:
pip3 install --user git+https://github.com/Deep-MI/qatools-python.git@freesurfer-module-releases#egg=qatoolspython
Use the following code to install the package in editable mode to a location of your choice:
pip3 install --user --src /my/preferred/location --editable git+https://github.com/Deep-MI/qatools-python.git@freesurfer-module-releases#egg=qatoolspython
Use import qatoolspython (or sth. equivalent) to import the package within a
python environment.
Use the run_qatools function from the qatoolspython module to run an
analysis:
from qatoolspython import qatoolspython
qatoolspython.run_qatools(subjects_dir='/my/subjects/dir', output_dir='/my/output/dir')
See help(qatoolspython) for further usage info and additional options.
We provide a Dockerfile that can be used to create a Docker image for the qatools-python scripts. Documentation is provided on the Docker page.
Included with this toolbox is a testing subdirectory which contains two
testing routines, testing.sh and testing.py. These can be used to test the
installation and verify results.
These operate on a subset of the Freesurfer tutorial data, which must be downloaded separately.
Extracting the downloaded file with tar -xzvf tutorial_data.tar.gz should
give a tutorial_data directory. From tutorial_data/buckner_data/tutorial_subjs/group_analysis_tutorial,
copy the following subjects to the testing/data subdirectory within the
toolbox directory: 017, 091, 092, 124, 129, 130, 136, and 145.
Run the tests by executing testing.sh and/or python3 testing.py from within
the testing subdirectory of this toolbox.
The program will analyze recon-all logfiles, and may fail or return erroneous results if the logfile is append by multiple restarts of recon-all runs. Ideally, the logfile should therefore consist of just a single, successful recon-all run.
- qatools-python: Kersten Diers, Tobias Wolff, and Martin Reuter.
- Freesurfer QA Tools: David Koh, Stephanie Lee, Jenni Pacheco, Vasanth Pappu, and Louis Vinke.
- shapeDNA and brainPrint toolboxes: Martin Reuter.
-
Esteban O, Birman D, Schaer M, Koyejo OO, Poldrack RA, Gorgolewski KJ; 2017; MRIQC: Advancing the Automatic Prediction of Image Quality in MRI from Unseen Sites; PLOS ONE 12(9):e0184661; doi:10.1371/journal.pone.0184661.
-
Wachinger C, Golland P, Kremen W, Fischl B, Reuter M; 2015; BrainPrint: a Discriminative Characterization of Brain Morphology; Neuroimage: 109, 232-248; doi:10.1016/j.neuroimage.2015.01.032.
-
Reuter M, Wolter FE, Shenton M, Niethammer M; 2009; Laplace-Beltrami Eigenvalues and Topological Features of Eigenfunctions for Statistical Shape Analysis; Computer-Aided Design: 41, 739-755; doi:10.1016/j.cad.2009.02.007.
-
Potvin O, Mouiha A, Dieumegarde L, Duchesne S, & Alzheimer's Disease Neuroimaging Initiative; 2016; Normative data for subcortical regional volumes over the lifetime of the adult human brain; Neuroimage: 137, 9-20; doi.org/10.1016/j.neuroimage.2016.05.016
-
A working installation of Freesurfer (6.0 or 7.11) must be sourced.
-
At least one structural MR image that was processed with Freesurfer 6.0, 7.11, or FastSurfer (including the surface pipeline).
-
A Python version >= 3.5 is required to run this script.
-
Required packages include (among others) the nibabel and skimage package for the core functionality, plus the matplotlib, pandas, and transform3d packages for some optional functions and modules. See the
requirements.txtfile for a complete list. Usepip3 install -r requirements.txtto install these packages. -
For the shape analysis module, the brainprint and lapy packages from https://github.com/Deep-MI are required (both version 0.2 or newer).
-
This software has been tested on Ubuntu 20.04 and MacOS 10.15.
This software is licensed under the MIT License, see associated LICENSE file for details.
Copyright (c) 2019 Image Analysis Group, DZNE e.V.