• eddyqc
• UsersGuide

WARNING This page is being edited in preparation for a new release

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.

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.

• vols_no_outliers.txt
  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

= Running SQUAD =