Add recommendations for distortion correction #896

tsalo · 2022-11-10T15:32:58Z

Closes #894.

Changes proposed in this pull request:

Add a FAQ on distortion correction.
Add a subsection to the multi-echo processing section on distortion correction.

docs/faq.rst

codecov · 2022-11-10T15:51:36Z

Codecov Report

Patch coverage: 96.18% and project coverage change: -4.34 ⚠️

Comparison is base (fb6e255) 93.30% compared to head (2468c26) 88.97%.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #896      +/-   ##
==========================================
- Coverage   93.30%   88.97%   -4.34%     
==========================================
  Files          28       27       -1     
  Lines        2346     3373    +1027     
  Branches        0      617     +617     
==========================================
+ Hits         2189     3001     +812     
- Misses        157      226      +69     
- Partials        0      146     +146

Impacted Files	Coverage Δ
tedana/decomposition/pca.py	`76.61% <ø> (-12.91%)`	⬇️
tedana/utils.py	`94.59% <ø> (-2.71%)`	⬇️
tedana/reporting/html_report.py	`91.39% <60.00%> (-8.61%)`	⬇️
tedana/reporting/static_figures.py	`96.34% <66.66%> (-2.45%)`	⬇️
tedana/docs.py	`77.35% <77.35%> (ø)`
tedana/reporting/dynamic_figures.py	`96.05% <81.25%> (-3.95%)`	⬇️
tedana/workflows/tedana.py	`80.95% <85.71%> (-8.68%)`	⬇️
tedana/io.py	`87.37% <87.35%> (-6.64%)`	⬇️
tedana/workflows/ica_reclassify.py	`97.79% <97.79%> (ø)`
tedana/selection/component_selector.py	`99.01% <99.01%> (ø)`
... and 7 more

... and 14 files with indirect coverage changes

☔ View full report in Codecov by Sentry.
📢 Do you have feedback about the report comment? Let us know in this issue.

docs/faq.rst

handwerkerd · 2022-11-15T16:50:46Z

docs/faq.rst

+you should use the first echo time's images to generate the undistortion transform,
+as long as that first echo has sufficient gray/white constrast to be useful for alignment
+(in which case, use the earliest echo that does have good contrast).
+


Suggested change

One potential issue is that the nonlinear spatial transforms that are part of distortion correction methods have the potential to skew the relationship between echoes. Specific examples of nonlinear alignments causing problems have not yet been observed.

Does this apply when the same transform is applied to all echoes? It seems like this is the problem our recommendation is meant to address.

I saw this issue on a dataset a while back that had non-trivial intensity inhomogeneity from the surface to the center of the brain. Even though interpolation is calculated using the same voxels in all echoes, the interpolation affected each echo a bit differently and messed up the relationship between the echoes. I really don't know how systematic or serious this issue is, but I've generally been cautious on using aggressive non-linear interpolations before combining echoes.

I feel like this has to be rare, though that observation does worry me. The main issue I see with stating something like it is preferable to avoid non-linear alignment is that this is in direct contrast with the default settings in AFNI, for example.

That said, I think the suggestion is good, because it will keep people on their toes. It does make me think it might be an issue that needs to be raised with AFNI in regards to what data goes into tedana (though its possible I missed some of the flexibility there).

handwerkerd · 2022-11-15T16:52:08Z

docs/faq.rst

+(in which case, use the earliest echo that does have good contrast).
+
+For context, please see
+`this NeuroStars thread <https://neurostars.org/t/multi-echo-pepolar-fieldmaps-bids-spec-sdcflows-grayzone/23933/5>`_.


I like the idea of starting to link to NeuroStars from our docs so that people know to go there with questions and we don't have to reword entire discussions with examples in the docs.

docs/multi-echo.rst

handwerkerd · 2022-11-15T16:54:02Z

docs/multi-echo.rst

+we recommend using your first echo time, as this will exhibit the least dropout.
+If your first echo time is very short, and exhibits poor gray/white contrast, then a later echo time may be preferable.
+In any case, you should calculate the spatial transform from just one of your echoes and apply it across all of them.
+


Lots of repetition in these two files. Not sure if we should add the warning about nonlinear transforms here as well.

I think this is ok, given that the nonlinear issues are relatively rare (I think and also hope). It also seems that the fix for this would not be on the users to generate special workflows, but instead on AFNI/fmriprep to run or save things at specific stages.

Co-authored-by: Dan Handwerker <7406227+handwerkerd@users.noreply.github.com>

jbteves · 2022-11-23T14:10:50Z

@tsalo since we have the 3.10 checks now, I made it mandatory, looks like your PR accidentally got caught. If you merge in main it should run and pass.

tsalo · 2022-11-23T14:27:35Z

Thanks @jbteves!

dowdlelt

I think it is good to go - there is enough detail there, even if it will require some (slight) modification in the future as more edge cases are discovered. I think it would be worth including Dan's suggestion about potential nonlinear issues, so that we have a warning there that we can build on in the future.

dowdlelt · 2022-12-15T17:32:51Z

docs/multi-echo.rst

+we recommend using your first echo time, as this will exhibit the least dropout.
+If your first echo time is very short, and exhibits poor gray/white contrast, then a later echo time may be preferable.
+In any case, you should calculate the spatial transform from just one of your echoes and apply it across all of them.
+


I think this is ok, given that the nonlinear issues are relatively rare (I think and also hope). It also seems that the fix for this would not be on the users to generate special workflows, but instead on AFNI/fmriprep to run or save things at specific stages.

dowdlelt · 2023-05-18T17:44:40Z

I maintain my approval here - but I will note that section 3 (which was left unchanged, and encourages distortion correction and normilization to be applied after tedana) somewhat disagrees with the new section 4. I don't think it is a major issue worth holding this up, but it just reflects that this isn't super tested.

handwerkerd · 2023-05-22T19:37:56Z

I'm going to merge this and we can tweak this text a bit more as part of #948

handwerkerd · 2023-05-22T19:58:41Z

New text is here: 290a7a8

I removed the recommendation to do distortion correction & normalization after tedana and I added a bit about normalization to the text on distortion correction. I also switched 3 & 4 & so we talk about what to do before tedana before talking about what goes after. The note was adjusted to justify why we do recommendation normalization & distortion correction first, but is retained as a warning to keep an eye on potential issues.

tsalo added 2 commits November 10, 2022 10:31

Add a FAQ.

dc76f0d

Add a subsection to the processing section on SDC.

3ce9142

tsalo added the documentation issues related to improving documentation for the project label Nov 10, 2022

Update faq.rst

3ed70ec

tsalo commented Nov 10, 2022

View reviewed changes

docs/faq.rst Outdated Show resolved Hide resolved

dowdlelt previously approved these changes Nov 10, 2022

View reviewed changes

docs/faq.rst Outdated Show resolved Hide resolved

Remove mentions of ultra-high resolution data.

e8f58f2

tsalo dismissed dowdlelt’s stale review via e8f58f2 November 11, 2022 20:39

tsalo requested review from handwerkerd and jbteves November 13, 2022 19:00

handwerkerd requested changes Nov 15, 2022

View reviewed changes

Apply suggestions from code review

a4ab46e

Co-authored-by: Dan Handwerker <7406227+handwerkerd@users.noreply.github.com>

Merge remote-tracking branch 'upstream/main' into doc-distortion

f7bdaa2

dowdlelt approved these changes Dec 15, 2022

View reviewed changes

Merge remote-tracking branch 'upstream/main' into doc-distortion

2468c26

handwerkerd approved these changes May 18, 2023

View reviewed changes

handwerkerd merged commit 9a3b83f into ME-ICA:main May 22, 2023

handwerkerd mentioned this pull request May 22, 2023

Multiple documentation updates #948

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add recommendations for distortion correction #896

Add recommendations for distortion correction #896

tsalo commented Nov 10, 2022

codecov bot commented Nov 10, 2022 •

edited

Loading

handwerkerd Nov 15, 2022

tsalo Nov 19, 2022 •

edited

Loading

handwerkerd Nov 22, 2022

dowdlelt Dec 15, 2022

handwerkerd Nov 15, 2022

handwerkerd Nov 15, 2022

dowdlelt Dec 15, 2022

jbteves commented Nov 23, 2022

tsalo commented Nov 23, 2022

dowdlelt left a comment

dowdlelt Dec 15, 2022

dowdlelt commented May 18, 2023

handwerkerd commented May 22, 2023

handwerkerd commented May 22, 2023


	One potential issue is that the nonlinear spatial transforms that are part of distortion correction methods have the potential to skew the relationship between echoes. Specific examples of nonlinear alignments causing problems have not yet been observed.

Add recommendations for distortion correction #896

Add recommendations for distortion correction #896

Conversation

tsalo commented Nov 10, 2022

codecov bot commented Nov 10, 2022 • edited Loading

Codecov Report

handwerkerd Nov 15, 2022

Choose a reason for hiding this comment

tsalo Nov 19, 2022 • edited Loading

Choose a reason for hiding this comment

handwerkerd Nov 22, 2022

Choose a reason for hiding this comment

dowdlelt Dec 15, 2022

Choose a reason for hiding this comment

handwerkerd Nov 15, 2022

Choose a reason for hiding this comment

handwerkerd Nov 15, 2022

Choose a reason for hiding this comment

dowdlelt Dec 15, 2022

Choose a reason for hiding this comment

jbteves commented Nov 23, 2022

tsalo commented Nov 23, 2022

dowdlelt left a comment

Choose a reason for hiding this comment

dowdlelt Dec 15, 2022

Choose a reason for hiding this comment

dowdlelt commented May 18, 2023

handwerkerd commented May 22, 2023

handwerkerd commented May 22, 2023

codecov bot commented Nov 10, 2022 •

edited

Loading

tsalo Nov 19, 2022 •

edited

Loading