This is a public code repository of the Translational BioImaging Resource–MRI core group at the University of Arizona.
Authors: Tom Hicks and Dianne Patterson
About: This project provides scripts, sample files, and documentation to use the QMTools project. QMTools is implemented as a Docker container. The container implements several programs to visualize, compare, and review the image quality metrics (IQMs) produced by the MRIQC program. MRIQC extracts no-reference IQMs from structural (T1w and T2w) and functional (BOLD) MRI data.
A corresponding Apptainer container can be built from the Docker image:
apptainer build qmtools_latest.sif docker://hickst/qmtoolsThis QMTools Support repository is designed to use the publicly available QMTools Docker container or a derived Apptainer container. Scripts, sample files, and documentation are provided to simplify this process. With this approach, the QMTools located in the container are called by the support scripts to process data from input and output directories which the scripts make available to the container. Since this approach requires only Docker or Apptainer, and the bash shell to be installed on the computer, it has a minimal "footprint".
To use the QMTools Support project:
Git clone this project somewhere within your "home" area and enter the cloned project directory.
Note: As an alternative to cloning with Git, you can download (and then unzip) the project from the project page at GitHub using the green Code button.
To clone this project from GitHub:
> cd /Users/janedoe/work
> git clone https://github.com/hickst/qmtools-support.git qmtools
> cd qmtools
> pwd
/Users/janedoe/work/qmtools
Note: Hereafter, this directory will be called the "project directory".
There are several directories which are made available to the QMTools container when you run a tool. These are inputs, reports, fetched, and queries, all of which are children of the project directory.
The inputs directory will be used to hold at least one of your group data files: i.e., a .tsv file output from a prior run of the MRIQC program at the group level.
The fetched directory will be used to hold IQM data retrieved from an online database of previously collected quality metrics that is maintained by the MRIQC group. For more information, see the documentation for the Fetcher program.
The reports directory will be used to hold visualizations and reports generated by the QMTools. Repeated runs of some QMTools may generate different sub-directories within the main reports directory.
The queries directory will be used to hold query parameters files: small files containing parameters for selectively fetching IQM records from the MRIQC server. The samples subdirectory contains several sample query parameters files that you can use as a starting point for your own parameterized queries.
Note: The QMTools scripts should always be run from the project directory.
In general, you will utilize the QMTools by copying MRIQC group files (IQM data files) into the inputs directory and/or by fetching IQM data from the MRIQC database server into the fetched directory. For each tool, a Bash script is included which makes the required directories available to the container and then starts the container to run the tool. Reports produced by the QMTools will be output to a sub-directory of the reports directory.
TrafficLight - Normalizes a set of MRIQC image quality metrics and creates a tabular HTML report visualizing how much each image's metrics deviate from the mean for all the images.
Fetcher - Queries the MRIQC database server to fetch image quality metrics for images previously processed by neuroimaging groups all over the world. A query may specify multiple image metadata parameters to filter the images whose metrics are returned. As query parameters may be read from user-created files, queries may be easily and consistently repeated.
Violin - Compares two sets of MRIQC image quality metrics and creates an HTML report, with Violin plots, visualizing how the two groups compare for each IQM. The two data sets to be compared can both be user-generated OR both fetched from the MRIQC database OR one of each.
Please see the individual tools documentation for instructions on running each tool.
The examples in the individual tools documenation are all for Docker. If you are using Apptainer instead, then the corresponding support scripts have *_hpc appended (e.g. use qmfetcher to run the Docker container and use qmfetcher_hpc to run the Apptainer container). If you are using Apptainer you should define a SIF environment variable indicating the directory where the Apptainer image qmtools_latest.sif resides. (The SIF environment variable in the script is set, by default, to the correct location for the U of Arizona HPC center).
The source code for the QMTools in GitHub.
The QMTools project was inspired by a 2019 Neurohackademy project available here.
The Swagger UI for the MRIQC web API. Scroll down to the Models section, which documents the database schema (structure and field names) that can be queried with Fetcher.
The source code for the MRIQC web API, which provides the API that Fetcher uses to query the MRIQC database.
Some old Discussions and Jupyter notebooks which utilize the same MRIQC web API that this project uses.
-
Esteban O, Blair RW, Nielson DM, Varada JC, Marrett S, Thomas AG et al. (2019). Crowdsourced MRI quality metrics and expert quality annotations for training of humans and machines. Sci Data 6: 30.
-
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.
This software is licensed under Apache License Version 2.0.
Copyright (c) The University of Arizona, 2021. All rights reserved.