#This is a template for a FSL tool sub-section # Create subpages as ToolName/blah # Remember to add this page to the appropriate category

<<FslToolContents>>

= 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.

 * [[https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/eddy/UsersGuide#Understanding_eddy_output|--cnr_maps]] <<BR>> 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.
 * [[https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/eddy/UsersGuide#A--repol|--repol]] <<BR>> 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.
 * [[https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/eddy/UsersGuide#A--mporder|--mporder]] <<BR>> 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:
 . [[https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/eddy/UsersGuide#A--out|<eddy_output_basename>]] <<BR>> Basename for EDDY output-files, i.e., corrected images and QC files.
 . [[https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/eddy/UsersGuide#A--index|-idx <eddy_index_file>, --eddyIdx=<eddy_index_file>]] <<BR>> Text file containing indices linking each acquired volume to the acquisition parameters
 . [[https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/eddy/UsersGuide#A--acqp|-par <eddy_acqparams_file>, --eddyParams=<eddy_acqparams_file>]] <<BR>> Text file containing acquisition parameters
 . [[https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/BET|-m <nodif_mask>, --mask=<nodif_mask>]] <<BR>> Binary mask file for the whole brain or a specific region. All voxel-wise QC metrics consider entries only from the marked voxels.
 . [[https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT/UserGuide#DTIFIT|-b <bvals>, --bvals=<bvals>]] <<BR>> b-values text file

 * Optional arguments:
 . [[https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/topup/TopupUsersGuide#A--fout|-f <fieldmap>, --field=<fieldmap>]] <<BR>> TOPUP estimated field (in Hz). When provided, QUAD will compute a voxel displacement map.
 . [[https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT/UserGuide#DTIFIT|-g <bvecs>, --bvecs=<bvecs>]] <<BR>> b-vectors text file - use only when storing the EDDY residuals.
 . [[https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/eddy/UsersGuide#A--slspec|-s <slspec>, --slspec=<slspec>]] <<BR>> Text-file describing slice acquisition order.
 . `-o <output folder>, --output-dir=<output folder>` <<BR>> Output directory - default = `<eddy_output_basename>.qc`.
 . `-v, --verbose` <<BR>> When set, display debug messages.

== Output ==
 * `qc.json` <<BR>> Single subject database containing quality metrics and data info.
 * `qc.pdf` <<BR>> Single subject QC report.
 * `avg_b*.png` <<BR>> Image showing mid-sagittal, -coronal and -axial slices of each averaged b-shell volume.
 * `avg_b0_pe*.png` <<BR>> Image showing mid-sagittal, -coronal and -axial slices of each averaged pe-direction b0 volume. Generated when using the `-f` option.
 * `cnr*.png` <<BR>> Image showing mid-sagittal, -coronal and -axial slices of each b-shell CNR volume. Generated when CNR maps are available.
 * `vdm.png` <<BR>> Image showing mid-sagittal, -coronal and -axial slices of the voxel displacement map. Generated when using the `-f` option.
 * `eddy_msr.txt` <<BR>> 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>` <<BR>> Text file containing a list of QUAD generated folders.

 * Optional arguments:
 . `-g <variable>, --grouping=<variable>` <<BR>> 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. <<BR>>

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]` <<BR>> 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>` <<BR>> 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>` <<BR>> Output directory - default = `squad`.

== Output ==
 * `group_db.json` <<BR>> Study-wise database containing quality metrics and data info.
 * `group_qc.pdf` <<BR>> Study-wise QC report.
 * `qc_updated.pdf` <<BR>> 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.