eddy-squeeze
Summarize and Visualize FSL Eddy Outlier Replacements
Contents
- Introduction
- Installation
- Dependencies
- How to use the script
Introduction
eddy-squeeze
eddy-squeeze is a tool that visualizes the signal replacements by FSL Eddy with --repol option. In addition to the visualization, it also collects measures like motions, number of outliers and post-eddy translations rom multiple eddy outputs into a csv and html file, for easier QC of FSL Eddy outputs.
- Eddy QC interested users should also check out
-
eddyqc (
eddy_squadandeddy_quad) by FSL that creates nice summary of a subject or a study wise summary of the Eddy outputs.
-
eddyqc (
FSL Eddy
- Eddy is a eddy-current, and head movement correction tool, from FSL, for the diffusion weighted images (DWI).
Eddy outlier replacement
- Using a Gaussian Process, Eddy builds a model of DWI data for each shell. And using this model, the prediction of DWI data for different B-shells becomes available, which is then used to make a comparison to the acquired data.
- If the comparison between the predicted signal and the actual signal is larger than anticipated, Eddy marks the signal (the slice in the volume) an outlier.
- It can also replace the signals in the outlier slices with that of predicted signal, reducing the large deviations from these outliers.
- Jesper L. R. Andersson and Stamatios N. Sotiropoulos. An integrated approach to correction for off-resonance effects and subject movement in diffusion MR imaging. NeuroImage, 125:1063-1078, 2016.
- Jesper L. R. Andersson, Mark S. Graham, Eniko Zsoldos and Stamatios N. Sotiropoulos. Incorporating outlier detection and replacement into a non-parametric framework for movement and distortion correction of diffusion MR images. NeuroImage, 141:556-572, 2016.
Installation
Install through Pypi
pip install eddy-squeeze
eddy_squeeze -hor download the repository
git clone https://github.com/pnlbwh/eddy-squeeze
Testing the eddy-squeeze using pytest
cd eddy-squeeze/tests
pytest test_eddy_squeeze.py
cd eddy-squeeze/tests/eddy_squeeze_lib
pytest test_eddy_files.py
pytest test_eddy_present.py
pytest test_eddy_utils.pyTesting the eddy-squeeze
cd eddy-squeeze/bin
./eddy_squeeze -h
Dependencies
FSL 6.0.1 EDDY outputs
FSLDIR in PATH
nifti-snapshot (https://github.com/pnlbwh/nifti-snapshot)
python 3.7
scipy==1.3.3
nibabel==2.4.0
numpy==1.16.2
pathlib2==2.3.3
matplotlib==3.0.3
tabulate==0.8.5
pytestHow to run eddy-squeeze
Collect output measures created by Eddy and prints them on screen
# one eddy output
eddy_squeeze --eddy_directories /test/eddy_out --print_table
# two eddy outputs
eddy_squeeze --eddy_directories /test/eddy_out1 /test/eddy_out2 --print_tableSave html summary
eddy_squeeze --eddy_directories /test/eddy_out1 /test/eddy_out2 \
--print_table \
--save_html \
--out_dir prac_eddy_summarySave html summary with figures
eddy_squeeze --eddy_directories /test/eddy_out1 /test/eddy_out2 \
--print_table \
--save_html \
--figure \
--out_dir prac_eddy_summaryExample outputs
eddy_squeeze \
--eddy_directories /prac_study_dir/subject01 /prac_study_dir/subject02 \
--print_tableOutput directory : /Users/kevin/eddy-squeeze/tests/bin/prac_eddy_summary
--------------------------------------------------
Setting up eddy directories
--------------------------------------------------
Extracting information from all eddy outputs
--------------------------------------------------
Summarizing 3 subjects
There is no eddy related files in ../prac_study_dir/subject03
n=2 eddy outputs detected
--------------------------------------------------
Basic information
--------------------------------------------------
+----+-----------+----------------------------+---------------------+---------------+---------------+---------------------------------------+-----------------+
| | subject | eddy_dir | number of volumes | max b value | min b value | unique b values | number of b0s |
|----+-----------+----------------------------+---------------------+---------------+---------------+---------------------------------------+-----------------|
| 0 | subject01 | /prac_study_dir/subject01 | 74 | 3000 | 0 | [ 0. 200. 500. 1000. 2950. 3000.] | 5 |
| 1 | subject02 | /prac_study_dir/subject02 | 74 | 3000 | 0 | [ 0. 200. 500. 1000. 2950. 3000.] | 5 |
+----+-----------+----------------------------+---------------------+---------------+---------------+---------------------------------------+-----------------+
Outlier information
--------------------------------------------------
+----+-----------+----------------------------+------------------------------------------------+-------------------------------------------------+---------------------------------------------------------------+
| | subject | number of outlier slices | Sum of standard deviations in outlier slices | Mean of standard deviations in outlier slices | Standard deviation of standard deviations in outlier slices |
|----+-----------+----------------------------+------------------------------------------------+-------------------------------------------------+---------------------------------------------------------------|
| 0 | subject01 | 80 | 894.399 | 11.18 | 6.30107 |
| 1 | subject02 | 80 | 894.399 | 11.18 | 6.30107 |
+----+-----------+----------------------------+------------------------------------------------+-------------------------------------------------+---------------------------------------------------------------+
Motion information
--------------------------------------------------
+----+-----------+--------------------------------+--------------------------------+
| | subject | absolute restricted movement | relative restricted movement |
|----+-----------+--------------------------------+--------------------------------|
| 0 | subject01 | 0.190404 | 0.112074 |
| 1 | subject02 | 0.190404 | 0.112074 |
+----+-----------+--------------------------------+--------------------------------+
Save summary html
eddy_squeeze \
--eddy_directories /test/eddy_out1 /test/eddy_out2
--out_dir eddy_summary \
--save_html
eddy_squeeze --eddy_directories /test/eddy_out1 /test/eddy_out2 --save_html --figure
From another python script
from eddy_squeeze import eddy_squeeze
# eddy output prefix list
eddy_prefix_list = ['/test/eddy_out1/subject01-eddy_out',
'/test/eddy_out1/subject02-eddy_out']
out_dir = '/data/pnl/prac/eddy_summary'
eddyDirectories = eddy_squeeze.EddyDirectories(eddy_prefix_list)
eddyDirectories.save_all_outlier_slices(out_dir)
eddyDirectories.create_group_figures(out_dir)
eddyDirectories.save_all_html(out_dir)
eddy_squeeze.create_study_html(eddyDirectories, out_dir=out_dir)
