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_squad and eddy_quad) by FSL that creates nice summary of a subject or a study wise summary of the Eddy outputs.
    • https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/eddyqc/UsersGuide

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 -h

or 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.py

Testing 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
pytest

How 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_table

Save html summary

eddy_squeeze --eddy_directories /test/eddy_out1 /test/eddy_out2 \
    --print_table \
    --save_html \
    --out_dir prac_eddy_summary

Save html summary with figures

eddy_squeeze --eddy_directories /test/eddy_out1 /test/eddy_out2 \
    --print_table \
    --save_html \
    --figure \
    --out_dir prac_eddy_summary

Example outputs

eddy_squeeze \
    --eddy_directories /prac_study_dir/subject01 /prac_study_dir/subject02 \
    --print_table

Output 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)