Newer
Older
-------------------------------------------
EDDY QC
Matteo Bastiani, FMRIB
August, 2017
-------------------------------------------
Automated tools based on FSL's eddy (https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/eddy) to perform quality assessment on diffusion mri (dMRI) datasets.
The eddy qc tools are currently distributed with FSL (v > 6.0.0, https://fsl.fmrib.ox.ac.uk/fsl/fslwiki).
If you want to install the tools within, e.g., your conda python environment, download the library and run:
Paper
-----
https://www.ncbi.nlm.nih.gov/pubmed/30267859
Wiki page
---------
https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/eddyqc
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
-------------------------------------------
QUAD (QUality Assessment for DMRI)
-------------------------------------------
Generates a QC report pdf and stores the QC indices in a .json file for single subject dMRI data.
The script will look for eddy output files that have been generated according to the user-specified options. If a feature, e.g., output the CNR maps, has not been used, then no CNR page will be added to the final report.
The script also produces a qc.json file that contains summery qc indices and basic information about the data. The JSON file can then be read by SQUAD to generate a group report.
Compulsory arguments:
eddyBase Basename (including path) specified when running EDDY
-idx, --eddyIdx File containing indices for all volumes into acquisition parameters
-par, --eddyParams File containing acquisition parameters
-m, --mask Binary mask file
-b, --bvals b-values file
Optional arguments:
-g, --bvecs b-vectors file - only used when <eddyBase>.eddy_residuals file is present
-o, --output-dir Output directory - default = '<eddyBase>.qc'
-f, --field TOPUP estimated field (in Hz)
-s, -slspec Text file containing acquisition details
-v, --verbose Display debug messages
Output:
output-dir/qc.pdf: single subject QC report
output-dir/qc.json: single subject QC and data info database
output-dir/vols_no_outliers.txt: text file that contains the list of the non-outlier volumes (based on eddy residuals)
Examples
--------
cd folder-where-eddy-output-is
Assuming eddy basename is "eddy_corrected"
Minimal running style:
eddy_quad eddy_corrected -idx eddyIndex.txt -par acqparams.txt -m nodif_brain_mask.nii.gz -b bvals
This will make a eddy_corrected.qc folder, where qc.pdf and qc.json will be stored.
Complete running style:
eddy_quad eddy_corrected -idx eddyIndex.txt -par acqparams.txt -m nodif_brain_mask.nii.gz -b bvals -g bvecs -f fieldmap.nii.gz -o qc_output_dir
This will make a qc_output_dir folder, where qc.pdf and qc.json will be stored. As bvecs were specified, the tool will also generate "clean" (i.e., outliers free) bvecs and bvals files, based on the eddy_residuals. A voxel displacement map will be obtained using the provided fieldmap (in Hz) and the standard deviation of the voxel displacement within the masked volume will be stored.
To clean the dataset, i.e., removing the outliers, run:
fslselectvols -i eddy_corrected -o eddy_corrected_clean --vols=qc_output_dir/vols_no_outliers.txt
-------------------------------------------
SQUAD (Study-wise QUality Assessment for DMRI)
-------------------------------------------
Generates a QC report pdf and database for whole-study dMRI data.
Updates single subject's report based on the study-specific database or using a previously generated one from a different study.
Groups the distributions of the QC indices based on a user-specified grouping variable.
The script will look for QUAD .json output files that are generated at the locations specified by the user in a text file.
Compulsory arguments:
list Text file containing a list of squad qc folders
Optional arguments:
-g, --grouping Text file containing grouping variable for the listed subjects
-u, --update [group_db.json] Update existing eddy_squad reports after generating group report or using a pre-existing [group_db.json] one
-gdb, --group-db Text file containing grouping variable for the database subjects
-o, --output-dir Output directory - default = '<eddyBase>.qc'
Output:
output-dir/group_qc.pdf: study-wise QC report
output-dir/group_db.json: study-wise QC database
Examples
--------
Assuming qc_folders.txt file is structured as:
subj1/eddy_corrected.qc
subj2/eddy_corrected.qc
subj3/eddy_corrected.qc
...
and group.txt file is structured as (first row is the label):
Group
1
0
1
...
Minimal running style:
eddy_squad qc_folders.txt
This will generate a quad directory where group_db.json (database) and group_qc.pdf (report) will be stored.
Complete running style:
eddy_squad qc_folders.txt -u -g group.txt -o quad_group
This will generate a quad_group directory where group_db.json (database) and group_qc.pdf (report) will be stored. Individual subjects' QC reports previously generated by QUAD will be updated by adding extra pages that will show the single sunject in the context of the study and marking QC indices as outliers in the tables where needed. Extra pages will be added to the report where distributions for individual QC indices will account for the specified grouping variable.
Using a previously generated database:
eddy_squad qc_folders.txt -u study/group_db.json -g group.txt -gdb group_db.txt -o quad_group
Same as before, but this time we are using a previously generated database to update the single subject reports. !!!NB!!! If using a grouping variable, it is required to specify the same grouping variable for the subjects of the previously generated database as a different variable.