[](https://doi.org/10.5281/zenodo.3600531)
# 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.
<br><br>
## Installation
### Install through Pypi
```sh
pip install eddy-squeeze
eddy_squeeze -h
```
### or download the repository
```sh
git clone https://github.com/pnlbwh/eddy-squeeze
```
##### Testing the eddy-squeeze using `pytest`
```sh
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
```
<br>
## Dependencies
```py
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
```sh
# 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
```sh
eddy_squeeze --eddy_directories /test/eddy_out1 /test/eddy_out2 \
--print_table \
--save_html \
--out_dir prac_eddy_summary
```
#### Save html summary with figures
```sh
eddy_squeeze --eddy_directories /test/eddy_out1 /test/eddy_out2 \
--print_table \
--save_html \
--figure \
--out_dir prac_eddy_summary
```
<br>
## Example outputs
```sh
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 |
+----+-----------+--------------------------------+--------------------------------+
```
<br>
#### Save summary html
```sh
eddy_squeeze \
--eddy_directories /test/eddy_out1 /test/eddy_out2
--out_dir eddy_summary \
--save_html
```
<br>
<br>
<br>
<br>
```sh
eddy_squeeze --eddy_directories /test/eddy_out1 /test/eddy_out2 --save_html --figure
```
#### From another python script
```py
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)
```
<br>
Raw data
{
"_id": null,
"home_page": "https://github.com/pnlbwh/eddy-squeeze",
"name": "eddy-squeeze",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "",
"author": "Kevin Cho",
"author_email": "kevincho@bwh.harvard.edu",
"download_url": "https://files.pythonhosted.org/packages/22/85/35672f6c848b7f971afcc1b451c3438f3129b027b6f5647a6bfc84ba36d0/eddy-squeeze-1.0.9.tar.gz",
"platform": null,
"description": "\n[](https://doi.org/10.5281/zenodo.3600531)\n\n\n# eddy-squeeze\n\n \n\n\n\n### Summarize and Visualize FSL Eddy Outlier Replacements\n\n\n\n\n\n\n## Contents\n- Introduction\n- Installation\n- Dependencies\n- How to use the script\n\n\n\n## Introduction\n\n\n### eddy-squeeze\n\n**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.\n\n- Eddy QC interested users should also check out\n - *eddyqc* (`eddy_squad` and `eddy_quad`) by FSL that creates nice summary of a subject or a study wise summary of the Eddy outputs.\n - https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/eddyqc/UsersGuide\n\n\n### FSL Eddy\n\n- Eddy is a eddy-current, and head movement correction tool, from FSL, for the diffusion weighted images (DWI).\n\n\n#### Eddy outlier replacement\n\n- 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.\n- 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.\n- It can also replace the signals in the outlier slices with that of predicted signal, reducing the large deviations from these outliers.\n - 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.\n - 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.\n\n\n\n\n<br><br>\n## Installation\n\n\n### Install through Pypi\n```sh\npip install eddy-squeeze\neddy_squeeze -h\n```\n\n\n### or download the repository\n\n```sh\ngit clone https://github.com/pnlbwh/eddy-squeeze\n```\n\n##### Testing the eddy-squeeze using `pytest`\n\n```sh\ncd eddy-squeeze/tests\npytest test_eddy_squeeze.py\n\ncd eddy-squeeze/tests/eddy_squeeze_lib\npytest test_eddy_files.py\npytest test_eddy_present.py\npytest test_eddy_utils.py\n```\n\n##### Testing the eddy-squeeze\n\n```\ncd eddy-squeeze/bin\n./eddy_squeeze -h\n```\n\n<br>\n\n## Dependencies\n\n```py\nFSL 6.0.1 EDDY outputs\nFSLDIR in PATH\nnifti-snapshot (https://github.com/pnlbwh/nifti-snapshot)\npython 3.7\nscipy==1.3.3\nnibabel==2.4.0\nnumpy==1.16.2\npathlib2==2.3.3\nmatplotlib==3.0.3\ntabulate==0.8.5\npytest\n```\n\n\n\n## How to run eddy-squeeze\n\n#### Collect output measures created by Eddy and prints them on screen\n```sh\n# one eddy output\neddy_squeeze --eddy_directories /test/eddy_out --print_table\n\n# two eddy outputs\neddy_squeeze --eddy_directories /test/eddy_out1 /test/eddy_out2 --print_table\n```\n\n\n#### Save html summary\n\n```sh\neddy_squeeze --eddy_directories /test/eddy_out1 /test/eddy_out2 \\\n --print_table \\\n --save_html \\\n --out_dir prac_eddy_summary\n```\n\n\n#### Save html summary with figures\n\n```sh\neddy_squeeze --eddy_directories /test/eddy_out1 /test/eddy_out2 \\\n --print_table \\\n --save_html \\\n --figure \\\n --out_dir prac_eddy_summary\n```\n\n<br>\n\n## Example outputs\n\n\n```sh\neddy_squeeze \\\n --eddy_directories /prac_study_dir/subject01 /prac_study_dir/subject02 \\\n --print_table\n```\n\n```\nOutput directory : /Users/kevin/eddy-squeeze/tests/bin/prac_eddy_summary\n--------------------------------------------------\n\nSetting up eddy directories\n--------------------------------------------------\n\nExtracting information from all eddy outputs\n--------------------------------------------------\nSummarizing 3 subjects\nThere is no eddy related files in ../prac_study_dir/subject03\n\nn=2 eddy outputs detected\n--------------------------------------------------\n\nBasic information\n--------------------------------------------------\n+----+-----------+----------------------------+---------------------+---------------+---------------+---------------------------------------+-----------------+\n| | subject | eddy_dir | number of volumes | max b value | min b value | unique b values | number of b0s |\n|----+-----------+----------------------------+---------------------+---------------+---------------+---------------------------------------+-----------------|\n| 0 | subject01 | /prac_study_dir/subject01 | 74 | 3000 | 0 | [ 0. 200. 500. 1000. 2950. 3000.] | 5 |\n| 1 | subject02 | /prac_study_dir/subject02 | 74 | 3000 | 0 | [ 0. 200. 500. 1000. 2950. 3000.] | 5 |\n+----+-----------+----------------------------+---------------------+---------------+---------------+---------------------------------------+-----------------+\n\nOutlier information\n--------------------------------------------------\n+----+-----------+----------------------------+------------------------------------------------+-------------------------------------------------+---------------------------------------------------------------+\n| | 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 |\n|----+-----------+----------------------------+------------------------------------------------+-------------------------------------------------+---------------------------------------------------------------|\n| 0 | subject01 | 80 | 894.399 | 11.18 | 6.30107 |\n| 1 | subject02 | 80 | 894.399 | 11.18 | 6.30107 |\n+----+-----------+----------------------------+------------------------------------------------+-------------------------------------------------+---------------------------------------------------------------+\n\nMotion information\n--------------------------------------------------\n+----+-----------+--------------------------------+--------------------------------+\n| | subject | absolute restricted movement | relative restricted movement |\n|----+-----------+--------------------------------+--------------------------------|\n| 0 | subject01 | 0.190404 | 0.112074 |\n| 1 | subject02 | 0.190404 | 0.112074 |\n+----+-----------+--------------------------------+--------------------------------+\n\n```\n\n\n<br>\n\n#### Save summary html\n\n```sh\neddy_squeeze \\\n --eddy_directories /test/eddy_out1 /test/eddy_out2\n --out_dir eddy_summary \\\n --save_html\n```\n<br>\n\n\n\n<br>\n\n\n\n<br>\n<br>\n\n```sh\neddy_squeeze --eddy_directories /test/eddy_out1 /test/eddy_out2 --save_html --figure\n```\n\n\n\n\n\n#### From another python script\n\n\n```py\n\nfrom eddy_squeeze import eddy_squeeze\n\n# eddy output prefix list\neddy_prefix_list = ['/test/eddy_out1/subject01-eddy_out',\n '/test/eddy_out1/subject02-eddy_out']\n\nout_dir = '/data/pnl/prac/eddy_summary'\n\neddyDirectories = eddy_squeeze.EddyDirectories(eddy_prefix_list)\n\neddyDirectories.save_all_outlier_slices(out_dir)\neddyDirectories.create_group_figures(out_dir)\n\neddyDirectories.save_all_html(out_dir)\neddy_squeeze.create_study_html(eddyDirectories, out_dir=out_dir)\n\n```\n\n<br>\n",
"bugtrack_url": null,
"license": "",
"summary": "Visualize extra information from FSL 6.0.1 eddy outputs",
"version": "1.0.9",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "77777d563a909c2e8f6ff65780e1ae8a",
"sha256": "7cdf34203aeb5138d3b11d810c123e69682161f519e60e2375b69659a66ab05d"
},
"downloads": -1,
"filename": "eddy-squeeze-1.0.9.tar.gz",
"has_sig": false,
"md5_digest": "77777d563a909c2e8f6ff65780e1ae8a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 114184,
"upload_time": "2022-12-10T04:25:31",
"upload_time_iso_8601": "2022-12-10T04:25:31.780292Z",
"url": "https://files.pythonhosted.org/packages/22/85/35672f6c848b7f971afcc1b451c3438f3129b027b6f5647a6bfc84ba36d0/eddy-squeeze-1.0.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-10 04:25:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "pnlbwh",
"github_project": "eddy-squeeze",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "tabulate",
"specs": [
[
">=",
"0.8.7"
]
]
},
{
"name": "matplotlib",
"specs": [
[
">=",
"3.0.3"
]
]
},
{
"name": "pandas",
"specs": [
[
">=",
"0.24"
]
]
},
{
"name": "numpy",
"specs": [
[
">=",
"1.1"
]
]
},
{
"name": "nibabel",
"specs": [
[
">=",
"3.1"
]
]
},
{
"name": "Jinja2",
"specs": [
[
">=",
"2.0"
]
]
},
{
"name": "pathlib2",
"specs": [
[
">=",
"2.3"
]
]
},
{
"name": "seaborn",
"specs": [
[
">=",
"0.9"
]
]
}
],
"lcname": "eddy-squeeze"
}
JSON
