[DOC] Update documentation for interacting with other pipelines

[emdupre]

Closes #112.

Changes proposed in this pull request:

• Creates a new RTD section to describe general MEEPI preprocessing pipelines
• Updates usage.rst to reference this new section

[codecov]

Codecov Report

Merging #134 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master     #134   +/-   ##
=======================================
  Coverage   48.72%   48.72%           
=======================================
  Files          32       32           
  Lines        2079     2079           
=======================================
  Hits         1013     1013           
  Misses       1066     1066

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 1508728...cdf5947. Read the comment docs.

[handwerkerd]

It looks like you've started the list of what preprocessing is required. I've sketched out my thought's below. I think it might be useful to separate current best practice from things that might matter, but haven't been tested. I'm sure I'm missing something obvious.

Main principles:

1. Do not do anything that mean shifts the data or separately scales the voxel wise values at each echo. Any intensity normalization or nuisance regressors should be applied to the data after tedana calculates the BOLD & non-BOLD weighting of components.
2. If the TR is slow enough to space out slices timing (probably TR>1s) then do slice timing correction
3. Apply the same spatial alignment & motion correction transforms to all echoes (i.e. calculate on the time series from one echo and apply to all echoes).
4. Mask the data so that only voxels with measurable signal changes in all echoes are included.

Acceptable steps before tedana include slice timing correction, despiking, motion correction, & spatial alignment.

Things that might matter:

1. I've seen some evidence that the spatial interpolation step for alignment/motion correction might matter. I had a data set with a large signal intensity gradient from the edge of the brain to the center. Things like quintic or sinc interpolation made nice looking images, but the intensity gradient varied between echoes & seemed to cause problems. For that data set, bilinear interpolation worked better, but I'm not sure if this is a universal issue, an issue when data is collected with many small receiver coils, or an anecdote

2. Masking decisions might matter. tedana has the potential to boost signal in areas of high dropout for volumes with T2* weighted echo times. Removing voxels in dropout regions removes this possibility, but keeping then can add potentially detrimental noise to the signal estimates.

3. The echo to use for motion correction & alignment might be study-specific. I think most people have used an echo with TE=25-30ms on a 3T scanner, but it's worth looking at data to identify which echo has sufficient spatial structure with minimal distortions to be useful for alignment & motion correction.

4. Motion correction is a standard step before tedana, but it's unclear if it's always necessary, particularly for very low motion subjects.

[tsalo]

Are there also recommendations for post-denoising processing steps? E.g., don't do bandpass filtering, do distortion correction and normalization after (but not before) denoising, etc.

[handwerkerd]

Trying to catch up on some comments here. I'm not sure there are definitive answers to @tsalo's questions from 2 weeks ago. I don't see any inherent problem with bandpass filtering after denoising. As commented elsewhere distortion correction is theoretically possible anywhere, but if it's done before denoising, it should be done in a way that preserves the raw magnitudes within voxels across all echoes. I'm not sure if any aggressive distortion correction pipeline has really validated this yet, but it should be possible.
Normalization is a confusing word because it can refer to alignment to a common space or mean normalization of time series (i.e. dividing each voxel time series by it's mean).
Spatial normalization should be ok as long as it's applied in the same way as motion correction would be applied. Similar to distortion correction, if spatial normalization uses aggressive non-linear warps, I'm not sure if anyone has really validated if this might cause problems.
Normalization of time series can be done after, but definitely not before denoising.

[emdupre]

I decided to convert this section to our general recommendations for preparing ME-EPI data for tedana. This is mostly a synthesis of conversations here and on gitter, but please let me know if you think I should have any other guidelines included !

[tsalo]

This looks good to me. It would be nice to have something that concisely summarizes how preprocessing should be split around tedana, but it's not necessary.

[emdupre]

Ok, I think I'm going to merge this ! We can always revisit later to add details.