Merge pull request #45 from handwerkerd/main

OHBM Brainhack 2025 updates to the book

Author: tsalo

_toc.yml

@@ -8,6 +8,7 @@ parts:
   - caption: Course Overview
     chapters:
     - file: content/Course_Overview
+    - file: content/Contributors
   - caption: Getting Started
     chapters:
     - file: content/00_Download_Data

content/Acquiring_Multi_Echo_Data.md

@@ -13,6 +13,67 @@ kernelspec:
 
 # Acquiring Multi-Echo Data
 
+## How to approach setting multi-echo acquisition parameters
+
+There is no definitively optimal parameter set for multi-echo fMRI acquisition or any fMRI acqusition.
+The guidelines for optimizing parameters are similar to single-echo fMRI.
+An overall recommendation is to choose single-echo sequence parameters that meet the priorities of a study with regards to spatial resolution,
+spatial coverage, sample rate, signal-to-noise ratio, signal drop-out, distortion, and artifacts.
+Then make the least significant parameter changes needed to acquire multi-echo fMRI data.
+"Least significant" is study-specific.
+In one study, one might have a 1.5 sec TR with single echo
+and multi-echo echo is possible with a 1.75 sec TR without impacting study goals.
+In another study, slices might cover cortex and cerebellum with the largest plausible participant brains, but 10% less coverage would include full brain coverage for most participants and all key study-specific regions-of-interest.
+
+A minimum of 3 echoes is required for methods like [tedana](https://tedana.readthedocs.io/en/stable/index.html) that fit echoes to a decay curve.
+There is typically at least one echo that is earlier and one that is later
+than the TE one would use for single-echo $T_2^*$ weighted fMRI.
+It is also important to make sure at least 3 echoes retain a useful amount of signal.
+On a 3T MRI, a few regions, particularly areas like orbitofrontal cortex, won't have sufficient signal for $TE\geq45ms$,
+and there will be more noticable signal loss with $TE\geq50ms$.
+There are multi-echo fMRI studies that successfully use longer 3rd echo times,
+but being aware of this signal loss is important,
+and one might benefit from keeping echo times shorter if one is prioritizing
+acquisitions in typically high signal dropout regions.
+
+More than 3 echoes may be useful, because that would allow for more accurate
+estimates of BOLD and non-BOLD weighted fluctuations, but more echoes have an
+additional time cost, which would result in either less spatiotemporal coverage
+or more acceleration.
+Whether the benefits of more echoes balance out the additional costs is an open research question.
+
+Additional recommendations and guidelines for acquiring multi-echo fMRI data
+are discussed in the [appendix of Dipasquale et al. (2017)](https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0173289)
+
+It is also useful to look at existing publications.
+
+- [Here is an always outdated list of multi-echo fMRI publications](https://docs.google.com/spreadsheets/d/1WERojJyxFoqcg_tndUm5Kj0H1UfUc9Ban0jFGGfPaBk/edit?gid=0#gid=0)
+- [Here is an often outdated list of multi-echo fMRI open datasets](https://me-ica.github.io/open-multi-echo-data/)
+that may be useful to visualize and measure data quality in datasets with similar scientific goals.
+
+[Here is a spreadsheet that shows possible acquisition parameters on a specfic 3T scanner](https://docs.google.com/spreadsheets/d/14iM6ENHrq9TGv6GhEe2dF9IzlM26y3aR9FmZGYXzmHA/edit?usp=sharing).
+This is useful to get a sense of what is possible when evaluating parameter options.
+That is, one can see how much a TR will increase for 3, 4, and 5 echoes for a given
+set of parameters and how different parameter changes, such as more acceleration,
+will alter the echo times and the TR.
+Note that this spreadsheet maps a wide range of parameter options
+and that go beyond advisable options.
+Just because it is possible to collect data with in-slice acceleration of 3
+and multi-slice acceleration of 4
+(a $\sqrt{12}$ drop in signal-to-noise ratio & more artifacts)
+doesn't mean it's advisable.
+
+Collecting and examining pilot scans is always recommended.
+Look at some data collected for your specific study.
+Look at signal quality, artifacts, dropout,
+and if potential effects of interest are sufficiently statistically robust.
+
+```{note}
+    There are other methods and use multi-echo acqusitions.
+    For example a **dual echo** method which uses a very early (~5ms)
+    first echo in order to clean data. For more information on this method, see [Bright and Murphy (2013)](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3518782/)
+```
+
 ## Available multi-echo fMRI sequences
 
 We have attempted to compile some basic multi-echo fMRI protocols in an [OSF project](https://osf.io/ebkrp/).
@@ -42,18 +103,13 @@ and make sure to run pilot scans to test your choices.
 
 ### GE
 
-**For GE users**, there are currently two sharable pulse sequences:
-
-- Multi-echo EPI (MEPI) – Software releases: DV24, MP24 and DV25 (with offline recon)
-- Hyperband Multi-echo EPI (HyperMEPI) - Software releases: DV26, MP26, DV27, RX27
-  (here hyperband can be deactivated to do simple Multi-echo EPI – online recon)
-
-Please reach out to the GE Research Operation team or each pulse sequence’s
-author to begin the process of obtaining this software.
-More information can be found on the [GE Collaboration Portal](https://collaborate.mr.gehealthcare.com).
-
-Once logged in, go to Groups > GE Works-in-Progress you can find the description
-of the current ATSM (i.e. prototypes).
+GE users can request access to the HyperMEPI ATSM sequence.
+Request can be made through [GE's WeConnect Portal](https://collaborate.mr.gehealthcare.com).
+This sequence has both hyperband,
+(GE's term for simultaneous-multislice or multiband) and multi-echo.
+Depending on scanner and software version,
+GE scanners have a limit on the total number of slices that can be collected during a single acquisition.
+This has the potential to limit the maximum duration of a multi-echo fMRI run.
 
 ### Philips
 
@@ -74,7 +130,7 @@ In addition to ME-fMRI, other MR sequences benefit from acquiring multiple
 echoes, including T1-weighted imaging (MEMPRAGE) and susceptibility weighted imaging.
 While most of these kinds of sequences fall outside the purview of this documentation,
 quantitative T2* mapping is relevant since a baseline T2* map is used in several
-processing steps including :ref:`optimal combination`.
+processing steps including optimal combination.
 While the T2* map estimated directly from fMRI time series is noisy, no current
 study quantifies the benefit to optimal combination or tedana denoising if a
 higher quality T2* map is used.
@@ -106,12 +162,6 @@ A minimum of 3 echoes is required for running the current implementation fo TE-d
 It may be useful to have at least one echo that is earlier and one echo that is later than the
 TE one would use for single-echo T2* weighted fMRI.
 
-```{note}
-This is in contrast to the **dual echo** denoising method which uses a very early (~5ms)
-first echo in order to clean data.
-For more information on this method, see {cite:t}`bright2013removing`.
-```
-
 More than 3 echoes may be useful, because that would allow for more accurate
 estimates of BOLD and non-BOLD weighted fluctuations, but more echoes have an
 additional time cost, which would result in either less spatiotemporal coverage

content/Contributors.md

@@ -0,0 +1,26 @@
+---
+jupytext:
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.10.3
+kernelspec:
+  display_name: Python 3
+  language: python
+  name: python3
+---
+
+# Contributors
+
+Taylor Salo ([@tsalo](https://github.com/tsalo/)) created this book by setting up the the initial repository,
+designing the overall framework that builds into an html Jupyter book,
+and wrote a substantial portion of the text.
+
+Daniel Handwerker ([@handwerkerd](https://github.com/handwerkerd)) led a project to expand and update this book at the [OHBM 2025 BrainHack](https://ohbm.github.io/hackathon2025).
+Mélanie Garcia ([@garciaml](https://github.com/garciaml)) made many substantial contributions.
+
+Additional contributors at the hackathon include
+
+- Merel van der Thiel [@merelvdthiel](https://github.com/merelvdthiel)
+- Korbinian Eckstein [@korbinian90](https://github.com/korbinian90)

content/Course_Overview.md

@@ -12,3 +12,30 @@ kernelspec:
 ---
 
 # Course Overview
+
+This book is a work-in-progress.
+
+The overall goal is to provide an understanding of how to think through
+collecting, analyzing, and interpreting multi-echo fMRI data.
+We tried to make this book accessible to someone without much
+math and physics expertise,
+but we also include equations to support people who want to understand
+multi-echo fMRI at a deeper level.
+Whenever we include equations, we try to explain the take-home message
+so that readers can follow the overall message without needing to study
+and understand every equation.
+
+This book covers several topics:
+
+- How to install the data and programs needed for running interactive examples
+- Information for understanding and thinking about acquiring multi-echo fMRI
+- How multi-echo information can be used to support noise removal in data
+- Examples and pipelines for processing and visualizing multi-echo data using multiple tools, such as AFNI, fMRIPrep and tedana.
+
+A good place to ask additional questions about multi-echo fMRI and processing is at
+[neurostars.org/](https://neurostars.org/) using the `multi-echo` or `tedana` tags.
+
+If you have ideas for future multi-echo fMRI methods or issues with the tedana code,
+you can post issues at [github.com/ME-ICA/tedana/issues](https://github.com/ME-ICA/tedana/issues) or
+start a discussion at [github.com/ME-ICA/tedana/discussions](https://github.com/ME-ICA/tedana/discussions).
+You can also join [mattermost.brainhack.org/brainhack/channels/tedana](https://mattermost.brainhack.org/brainhack/channels/tedana) for additional discussions with tedana developers.

content/Install_Software.md

@@ -12,3 +12,24 @@ kernelspec:
 ---
 
 # Install Software
+
+## tedana
+
+Instructions for installing tedana are [in the tedana documentation](https://tedana.readthedocs.io/en/stable/installation.html)
+
+[Here is a list of tedana's python dependencies](https://github.com/ME-ICA/tedana/blob/main/pyproject.toml)
+
+If you are interested in using a pre-release version of tedana
+or are interested in contributing to the tedana code,
+[instructions for cloning the code, and installing as a developer are here.](https://github.com/ME-ICA/tedana/blob/main/CONTRIBUTING.md#3-run-the-developer-setup)
+
+## AFNI
+
+AFNI can preprocess multi-echo fMRI data run it through tedana for denoising.
+[Instructions for installing AFNI are here](https://afni.nimh.nih.gov/pub/dist/doc/htmldoc/background_install/main_toc.html)
+
+
+## fMRIPrep
+
+fMRIPRep can preprocess multi-echo fMRI data and run the optimal combination of echoes through tedana.
+[Instructions for installing fMRIPrep are here](https://fmriprep.org/en/stable/installation.html)

content/MR_Physics.md

@@ -22,38 +22,38 @@ For this reason, hydrogen is the most widely used in MRI.
 
 MRI bore contains a powerful magnet which generates an uniform magnetic field B0.
 Patiens are introduced in this magnetic field and hydrogen atoms align to the magnetic field.
-According to Larmour's law, a magnetic dipole inside a magnetic field
+According to Larmor's law, a magnetic dipole inside a magnetic field
 precesses (spins) around the magnetic field with a frequency proportional to the magnetic field strength.
 Hence, hydrogen atoms precess around the magnetic field generated by the MR with a frequency (Larmor frequency) that follows the equation:
 
 w =  γ B0
 
 ![](https://www.frontiersin.org/files/Articles/427144/frym-07-00023-HTML-r2/image_m/figure-2.jpg)
+
 This precession can be parallel or antiparallel to B0.
 In the body the number of atoms that precess parallel is different to
 the ones that precess antiparallel producing an small magnetic field which is proportional to B0 and also depends on the density
 of hydrogen nuclei.
 So, the static magnetic field (B0) induces a slight magnetization of tissues.
 
-Then, a radiofrequency pulse is emitted perpendicular to B0 with the same frequency that the spin precession frequency.
-Hydrogen atoms abrorb energy and spin out of equilibrium.
+Then, a radiofrequency (RF) pulse is emitted perpendicular to B0 with the same frequency that the spin precession frequency.
+Hydrogen atoms absorb energy and spin out of equilibrium.
 Longitudinal magnetization (Mz) of protons in a parallel direction to B0 decreases,
 and a transverse magnetization (Mx, My) appears.
 
 Then, when the RF disappears,
-the magnetic momentum gradually goes back to te minimum energy position (magnetic relaxation) while releasing energy.
+the magnetic momentum gradually goes back to the minimum energy position (magnetic relaxation) while releasing energy.
 These emitted signals are measured into the k-space,
 which is an array of numbers representing spatial frequencies in the MR image.
 (Each k-space point contains spatial frequency and phase information about every pixel in the final image).
-Fourier transforme is performed to the k-space to obtain the final image.
+Fourier transform is performed to the k-space to obtain the final image.
 By varying the sequence of RF pulses applied & collected, different types of images are created.
 
 
 ### MRI Sequences
 
 It's important to understand the meaning of **repetition time (TR)** and **echo time (TE)** in order to comprehend the main MRI sequences.
-Time to Echo (TE) is the time between the delivery of the RF pulse and the receipt of the echo signal and
-the interval between subsequent pulse sequences delivered to the same slice is known as the repetition time (TR).
+Time to Echo (TE) is the time between the delivery of the RF pulse and the receipt of the echo signal. The interval between subsequent pulse sequences delivered to the same slice is known as the repetition time (TR).
 
 The most common sequences are T1-weighted and T2-weighted images.
 In neuroimaging, **T1-weighted** images are commonly used in anatomical related studies,

content/Multi_Echo_Datasets.md

@@ -14,8 +14,16 @@ kernelspec:
 (content:open-datasets)=
 # Open Multi-Echo Datasets
 
-A number of multi-echo datasets have been made public so far.
-This list is not necessarily up to date, so please check out OpenNeuro to potentially find more.
+A running list of openly accessible multi-echo fMRI datasets is at:
+[me-ica.github.io/open-multi-echo-data/](https://me-ica.github.io/open-multi-echo-data/).
+If you know of other datasets that should be added,
+submit an issue at [github.com/ME-ICA/open-multi-echo-data/issues](https://github.com/ME-ICA/open-multi-echo-data/issues)
+or each out to a [tedana developer](https://github.com/ME-ICA/tedana/graphs/contributors)
+
+```{important}
+The datasets below were added before the above spreadsheet was created. They do have some additional context.
+Need to decide how much of that context is worth preserving vs just deleting.
+```
 
 ## Multi-echo fMRI replication sample of autobiographical memory, prospection and theory of mind reasoning tasks