May 11, 2023 tedana newsletter
tedana-newsletter
We are actively developing tedana, but we have not published a newsletter in 2 years. If you know others who might appreciate this information, please share with them and invite them to subscribe. This really is an infrequent newsletter, so we won’t fill up your inboxes.
We have just released a major update to tedana. We also switched to year-based version numbering so the version for this update is 23.0.1. If you type pip install tedana this is the version you will install. This release changes many internal aspects of the code, will make future improvements easier, and will hopefully make it easier for more people to understand their results and contribute. The denoising results should be identical. Right before releasing this new version, we released version 0.0.13, which is the last version of the older code. If you want to confirm the consistency of results, these are the two versions you should compare. Instructions for comparing results are below.
- Large portions of the code were reorganized and modularized to make understanding the code easier and facilitate future development
- Breaking change: tedana can no longer be used to manually change component classifications. A separate program, ica_reclassify, can be used for this. This makes it easier for programs like Rica to output a list of component numbers to change and to then change them with ica_reclassify.
- The component classification process that designates components as “accepted” or “rejected” was completely rewritten so that every step in the process is modular and the inputs and outputs of every step are logged. The documentation includes descriptions of the newly outputted files and file contents.
- It is now possible to select different decision trees for component selection using the --tree option. The default tree is kundu and should replicate the current outputs. We also include minimal which is a simpler tree that is intended to provide more consistent results across a study, but still needs more testing and validation and may still change. Flow charts for these two options are here.
- Anyone can create their own decision tree. If one is using metrics that are already calculated, like kappa and rho, and doing greater/less than comparisons, one can make a decision tree with a user-provided json file. More complex calculations might require editing the tedana python code. This change also means any metric that has one value per component can be used in a selection process. This makes it possible to combine the multi-echo metrics used in tedana with other selection metrics, such as correlations to head motion. The documentation includes instructions on building and understanding this component selection process.
- Breaking change: No components are classified as ignored. “Ignored” has long confused users. It was intended to identify components with such low variation that it wasn’t worth deciding whether to lose a statistical degree of freedom by rejecting them. They were treated identically to accepted components. Now they are classified as “accepted” and tagged as “Low variance” or “Borderline Accept”. These classification tags now appear on the html report of the results.
- A registry of all files outputted by tedana is now stored with the outputs. This allows for multiple file naming methods and means internal and external programs that want to interact with the tedana outputs just need to load this file.
- Nearly 100% of the new code and 98% of all tedana code is covered by integration testing.
- Tedana python package management now uses pyproject.toml
- Minimum python version is now 3.8 and minimum pandas version is now 2.0 (might cause problems if the same python environment is used for packages that require older versions of pandas)
- More comprehensive documentation of changes is in pull request #756 and the full release notes are here: https://github.com/ME-ICA/tedana/releases/tag/23.0.1
- Breaking change: Corrected a bug where the component classification process should have calculated a threshold on a sorted list of component variances, but it was calculated on an unsorted list. (#924).
- Breaking change: In v0.0.12 we changed the default method for selecting the number of components from MDL to AIC, but later realized this was only implemented when run through python, but not from the command line. Now AIC is the default for both. (#877)
- Optimization curves and additional info for the PCA dimensionality reduction step are saved to help users and developers identify problems with the step that identifies the number of components to use (#839)
- Added Python 3.10 compatibility (#818)
- Using BibTeX instead of duecredit for listing references. Warnings messages about users not having duecredit installed are gone (#875)
- Tedana python package management now uses setup.cfg (#874)
- Multiple documentation changes. Full release notes are here: https://github.com/ME-ICA/tedana/releases/tag/0.0.13
We welcome more people checking to confirm our old and new code give identical results. dtm_tools is a package that will facilitate results comparisons and includes instructions for how to run tedana and compare across versions. Note that the results from PCA and ICA vary depending on versions of libraries outside of tedana, like scikit-learn, hardware, and software variations. To remove this source of variation in results, calculate the ICA mixing matrix in one version of tedana and use the --mix option to use the same ICA mixing matrix for the other version of tedana. We are happy to answer questions and help anyone who is interested in running tests.
We are excited to welcome new contributors: @n-reddy, @marco7877, @giadaan, @aryangupta701, @pablosmig, @Kasambx, and @pmolfese! Thanks to all of our contributors for their continued input and help in creating tedana. We also want to specifically thank Josh Teves, who has recently taken a job outside of neuroimaging, for substantial contributions to tedana over many years. 26 people have directly contributed code or documentation to the project and many others have contributed through questions, ideas, and feedback. We always look forward to seeing more new faces! If you’re not sure where to start, please feel free to open an issue on gitub, ask a question on neurostars with the ‘tedana’ or ‘multi-echo’ tag, join our next monthly developer’s call, or join the tedana mattermost channel.
The Section on Functional Imaging Methods at NIMH is hiring a scientific programmer. This position will include making contributions to tedana. Please share with anyone who might be interested.