- Users Guide
The EDDY QC tools
The EDDY QC framework consists of two different tools that automatically perform QC both at the single subject and study-wise level.
QUAD (QUality Assessment for DMRI) generates single subject reports and stores the quality assessment indices for each subject.
SQUAD (Study-wise QUality Assessment for DMRI) reads all the single subject outputs from QUAD, generates study-wise reports and, optionally, enters these into a database. Moreover, SQUAD can optionally update single subject reports, indicating how the subject’s dataset compares to other data, using either a study-specific group database or a pre-generated database obtained from a different dataset. Lastly, SQUAD also allows to report QC indices based on user-provided variables.
The tools can be called from the command line using eddy_quad and eddy_squad.
If you haven't already run EDDY on your data
The availability of different QC metrics depends on the exact options that EDDY was run with. This is determined by the EDDY QC tools based on what EDDY output files are present. E.g., metrics related to outlier slices are not calculated when the corresponding EDDY option has not been used. The following list contains the non-compulsory EDDY input parameters you may want to use when running EDDY to obtain more QC metrics.
By setting this flag, a 4D image file with N+1 volumes where N is the number of non-zero b-value shells will be generated by EDDY. The first volume contains the voxelwise SNR for the b=0 shell and the remaining volumes contain the voxelwise CNR (Contrast to Noise Ratio) for the non-zero b-shells in order of ascending b-value. The eddy QC tools will use this image file to obtain b-shell-wise SNR and CNR metrics averaged within the provided binary mask.
This flag instructs EDDY to remove any slices deemed as outliers and replace them with predictions made by the Gaussian Process. The EDDY QC tools will derive outliers-related QC metrics like, e.g., total % of outlier slices across the whole dataset.
If --mporder is set to an integer value greater than 0 and less than the number of excitations in a volume, EDDY corrects for within-volume motion artefacts. The EDDY QC tools will use the generated output to compute within-volume displacements and rotations QC metrics.
QUAD expects an EDDY output basename to identify the relevant output files that have been generated according to some user-specified options. If a feature, e.g., outliers detection and replacement, was not used, the outliers-related quality metrics will not be included in the final report nor added to the single-subject database. The most basic way to run eddy_quad after having pre-processed the dMRI dataset consists in running the following example command:
eddy_quad <eddy_output_basename> -idx <eddy_index_file> -par <eddy_acqparams_file> -m <nodif_mask> -b <bvals>
This will result in the creation of a new folder, called <eddy_output_basename>.qc. This will contain the single subject QC report and database, together with the slices included in the report stored as single image files.
List of input parameters
- Compulsory arguments:
Basename for EDDY output-files, i.e., corrected images and QC files.
-idx <eddy_index_file>, --eddyIdx=<eddy_index_file>
Text file containing indices linking each acquired volume to the acquisition parameters
-par <eddy_acqparams_file>, --eddyParams=<eddy_acqparams_file>
Text file containing acquisition parameters
-m <nodif_mask>, --mask=<nodif_mask>
Binary mask file for the whole brain or a specific region. All voxel-wise QC metrics consider entries only from the marked voxels.
-b <bvals>, --bvals=<bvals>
b-values text file
- Optional arguments:
-f <fieldmap>, --field=<fieldmap>
TOPUP estimated field (in Hz). When provided, QUAD will compute a voxel displacement map.
-g <bvecs>, --bvecs=<bvecs>
b-vectors text file - use only when storing the EDDY residuals.
-s <slspec>, --slspec=<slspec>
Text-file describing slice acquisition order.
-o <output folder>, --output-dir=<output folder>
Output directory - default = <eddy_output_basename>.qc.
When set, display debug messages.
Single subject database containing quality metrics and data info.
Single subject QC report.
Image showing mid-sagittal, -coronal and -axial slices of each averaged b-shell volume.
Image showing mid-sagittal, -coronal and -axial slices of each averaged pe-direction b0 volume. Generated when using the -f option.
Image showing mid-sagittal, -coronal and -axial slices of each b-shell CNR volume. Generated when CNR maps are available.
Image showing mid-sagittal, -coronal and -axial slices of the voxel displacement map. Generated when using the -f option.
Text file containing the volume-wise mask-averaged squared residuals. Generated when residual maps are available.
Text file containing a list of clean volumes, based on the eddy squared residuals. To generate a version of the pre-processed dataset without outlier volumes, use:
fslselectvols -i <eddy_corrected_data> -o eddy_corrected_data_clean --vols=vols_no_outliers.txt
SQUAD expects a list of single-subject QC folders generated by QUAD. The study-wise tool has been designed to allow maximum flexibility in terms of QC capabilities. The most basic way to run eddy_squad after having pre-processed the dMRI dataset consists in running the following example command:
This will result in the creation of a new folder, called squad. This will contain the study-wise QC report and database.
List of input parameters
- Compulsory arguments:
Text file containing a list of QUAD generated folders.
- Optional arguments:
-g <variable>, --grouping=<variable>
Text file containing a continuous or discrete variable for the listed subjects. This variable will be used to generate two different types of plots in the study-wise report. If the variable is categorical, violin plots showing the distributions of most QC metrics for each class will be added to the report. If the variable is continuous, scatter plots with a linear regression model fit will be added to the report.
The right way to format the text file listing the values associated to each subject is this:
VarName 0 [1 for continuous] v_1 v_2 . . . v_n
The first line contains a string specifying the variable label; the second line contains either 0 or 1 to let SQUAD know whether the variable is categorical or continuous, respectively. Then there are n entries, where n is the number of subjects (i.e., QUAD folders) specified in the list file.
-u, --update [group_db.json]
Update existing eddy_squad reports after generating group report or using a pre-existing [group_db.json] one.
-gdb <db_variable>, --group-db=<db_variable>
Text file containing a categorical or continuous variable for the pre-existing database. The format is the same as the one used before.
-o <output_dir>, --output-dir=<output_dir>
Output directory - default = squad.
Study-wise database containing quality metrics and data info.
Study-wise QC report.
This file will be generated in each listed folder when updating the single-subject QC reports. Single QC metrics will be flagged as outliers and highlighted using a traffic-light colouring system on the first page. Extra pages will be added to the original single-subject QC report containing study-wise plots where the subject's performance are clearly highlighted.