Documenting scripts to prepare ROI time series & create external regressors

[handwerkerd]

Summary

External regressor metric calculations are currently set up so that users provide a tsv file of time series. This means, if someone wants to use an ROI-based external regressor, one needs to calculate an average time series on single-echo data or a separately run optimal combination of the echoes. This is mildly impractical.

Additional Detail [updated]

After discussion at our Feb 2025 developers' call, the decision was that adding code to average ROIs into tedana would be scope-creep and require non-trivial work. See first comment below. The revised plan is to document guides for how to create and input external regressors using various pipelines

Next Steps

1. Find people to volunteer to make demo scripts for various pipelines.
   • Maybe @tsalo for fMRIPrep
   • Maybe@handwerkerd, @goodalse2019, and/or @mmedina002 makes ones for AFNI (@afni-rickr can review)
2. Discuss exactly what we want to demo & where it would go in our docs/code
3. Wait until the above people actually have the time to do this
4. In speaking with @afni-rickr, once we have something we're happy with, it might be tricky to add directly into afni_proc, but it might be possible for AFNI to distribute a script to make this easier.

[original issue text]

Additional Detail

It would be useful to add an option to provide an ROI mask in the same space as the EPI data and have the average ROI time series calculated within tedana. There are several reasons this wasn't included in the origin external regressors PR and several decision points to help decide the best way to set this up:

1. The simplicity of external regressors is that users provide a tsv file with columns numbers. tedana reads in numbers and doesn't need any additional processing. My suggestion for adding this functionality would be to allow a user to provide a file name under a column header. It should still be possible to read in the tsv file, but then we'd need add code to parse the tsv file to look for a column with a word rather than numbers. This wouldn't be too hard, but it's not particularly elegant. Any better ideas? Separate input parameters?
2. There are several approaches to calculate the average time series within an ROI (traditional mean, the highest variance or top three highest variance singular vectors (i.e. SVD or PCA). We should decide how flexible we want to be and how users would provide this info. As input parameters? As another line in the tsv file? If we allow top 3, would that mean one column of input in the tsv file becomes 3 columns of numbers?
3. We are already including the tsv file in the output directory so this would replace the inputted tsv file with one that includes the ROI averaged time series. Would we want to document anything else somewhere besides in the log?

Next Steps

1. Get feedback on design decisions
2. Prioritize compared to other issues
3. Find time to actually code this. @goodalse2019 expressed some willingness to code this with support from me.

[tsalo]

My default is not to expand tedana's flexibility- it is already a very complicated tool with many knobs people can tune. I propose writing instructions for how to create ROI time series and use them in tedana, rather than adding this functionality to tedana directly. Maybe we could have a repo of scripts for how people can do this (or add as examples in https://me-ica.github.io/multi-echo-data-analysis/content/intro.html).

With fMRIPrep, you get out optimally combined data in the requested output spaces, so there isn't much burden to applying whatever masks you want (in native or template spaces), using your preferred summarization method (mean, PCA, ICA, NMF, etc.) and providing the time series as an external regressor. Based on what @handwerkerd said, it seems like that's not the case with afni_proc.py, where the actual workflow would need to be changed since tedana is run internally. @handwerkerd was going to check with the AFNI folks to see if it would be possible to handle it on afni_proc.py's side.

[afni-rickr]

Hi @tsalo. I agree that such computations should be done by afni_proc.py rather than tedana.

Yes, @handwerkerd is correct as usual. While motion terms should be immediately available for tedana, ROI averages and PCs are computed later, when preparing for the final regression. Regardless, such a prep for tedana would require different functionality, since averages would presumably come from an OC dataset (we can call our own function for that, too). But this certainly seems doable.