• eddyqc
• UsersGuide

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.

• --cnr_maps
  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.

• --repol
  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.

• --mporder
  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.

Running QUAD

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:

• <eddy_output_basename>
  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.

• -v, --verbose
  When set, display debug messages.

Output

• qc.json
  Single subject database containing quality metrics and data info.

• qc.pdf
  Single subject QC report.

• avg_b*.png
  Image showing mid-sagittal, -coronal and -axial slices of each averaged b-shell volume.

• avg_b0_pe*.png
  Image showing mid-sagittal, -coronal and -axial slices of each averaged pe-direction b0 volume. Generated when using the -f option.

• cnr*.png
  Image showing mid-sagittal, -coronal and -axial slices of each b-shell CNR volume. Generated when CNR maps are available.

• vdm.png
  Image showing mid-sagittal, -coronal and -axial slices of the voxel displacement map. Generated when using the -f option.

• eddy_msr.txt
  Text file containing the volume-wise mask-averaged squared residuals. Generated when residual maps are available.

Running SQUAD

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:

eddy_squad <quad_folders>

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:

• <quad_folders>
  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.

Output

• group_db.json
  Study-wise database containing quality metrics and data info.

• group_qc.pdf
  Study-wise QC report.

• qc_updated.pdf
  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.