ME-ICA/tedana: 25.0.0

Release Notes

Breaking

• Properly flip ICA mixing matrix time series by @handwerkerd in https://github.com/ME-ICA/tedana/pull/1212 ICA components were multiplied by -1 so that the component weight maps had more positive than negative values. The weight maps were saved flipped, but the time series were not. This was documented and interally handled correctly, so it wasn't a bug, but it was unnecessarily confusing. Now the time series are also flipped. This means, if you run tedana with a predefined mixing matrix some of the component time series may be flipped in the outputted mixing matrix.

🐛 Bug Fixes

• Back-fill, then forward-fill, NaNs in external regressors by @tsalo in https://github.com/ME-ICA/tedana/pull/1163
• Add option to overwrite file (and write out extra files with "verbose") in T2smap workflow by @smoia in https://github.com/ME-ICA/tedana/pull/1166

Enhancements

• Adding a degree of freedom (dof) flag (--n-independent-echos) to allow users to set the dof used in fstat calculations by @katielamar in https://github.com/ME-ICA/tedana/pull/1177 EPTI sequences can be used to collect many echoes, but these echoes are not independent. This option lets users set the number of independent echoes (i.e. the number of basis functions used to reconstruct EPTI data) and means tedana will now work properly with EPTI data.
• Show interactive plot of Robust ICA clusters in the HTML reports by @eurunuela in https://github.com/ME-ICA/tedana/pull/1153 The -ica_method robustica option was added in v24.0.2 With the goal of helping interpret RobustICA output, this adds an interactive figure to the tedana_report that is described in our documentation. This visualization is still a work-in-progress but we decided it was better to add so that people can use it and provide feedback.
• More info logged for robustICA by @handwerkerd in https://github.com/ME-ICA/tedana/pull/1218 RobustICA runs multiple iterations of ICA and identifies stable clusters across iterations. While ICA can sometimes fail to converge, if it repeated fails to converge, that's the sign of something wrong with the data inputted into the ICA. This redirects a on-screen-only message from RobustICA that appeared every time an iteration of ICA failed to converge and adds a counter that is logged within tedana. If more than 10% of iterations fail to converge, tedana outputs a warning. Failure to converge is typically caused by providing too many PCA components to ICA, but it can also happen with too few initial PCA components. If this warning appears, consider using --tedpca [integer] to set the initial number of components.
• New QC measure for fit of rejected to accepted components by @marlyr in https://github.com/ME-ICA/tedana/pull/1208 Rejected and Accepted component time series are not orthogonal. This adds a new quality measure that is included in the hover text of the tedana_report that shows the percent of variance explained by rejected components for each accepted component. A borderline component that is very similar to other rejected components might be worth rejecting. desc-ICACrossComponent_metrics.json also contains total_var_exp_rejected_components_on_accepted which is an overall summary metric. If this is higher than other runs in a dataset, that run might be worth examining more closely. This option is essentially the reverse of the --tedort option which removes variance explained by accepted components from the rejected components. Particularly if these new values are high, this option can be used as a conservative way to reduce the likelihood of rejecting relevant signal.
• Adding classification tags options to ica_reclassify by @handwerkerd in https://github.com/ME-ICA/tedana/pull/1200 ica_reclassify defaults to tagging any components it changes as manual reclassify The new --tagacc and --tagrej options allow for user-provided alternatives. This might be useful if someone is classifying components with some other method and want to use that method to label changes or if individuals are making manual changes and want to log which individual made each change.
• Download decision trees from figshare by @marlyr in https://github.com/ME-ICA/tedana/pull/1217 Now that users can create their own decision trees, we needed a way to efficiently share those trees. If you have a tree that is used in a manuscript under review or a published manuscript, you can request adding it to our figshare page. Then, with the input `--tree [your_tree_name], tedana will download the tree from figshare.
• Add a function to check if TE values are in ms, otherwise update them by @eurunuela in https://github.com/ME-ICA/tedana/pull/1151 Prevents a too common mistake of users entering the echo times with the wrong units.
• add warning for when tedana calculates mask by @handwerkerd in https://github.com/ME-ICA/tedana/pull/1203 Tedana developers frequently get asked why tedana is removing too many voxels. The answer is usually because users applied tedana's build-in masking option which is ok & good for testing things out, but not as reliable as masking options build into other standard pipelines. We strongly recommend people use masks generated from other pipelines and visually evaluate the quality of those masks. When people use tedana's default masking method, this outputs a warning to advise using a more reliable mask.
• Add verbose option to ica_reclassify to obtain denoised echo images by @eurunuela in https://github.com/ME-ICA/tedana/pull/1179

Project maintenance and under-the-hood stuff

• Require only one approving review for minor pull requests by @tsalo in https://github.com/ME-ICA/tedana/pull/1135 This is a modest change to the code but it gets credit for the tedana developers finally finishing many of the additions in this release. We still wait for two reviews for substantial changes, but valuable changes that only lightly alter the code are getting merged faster.
• Add dash versions of underscore params by @tsalo in https://github.com/ME-ICA/tedana/pull/1147 Reduces program crashes when users use - instead of _ in parameter names
• Use Jinja2 to populate reports and deal with empty spaces when figures aren't added by @eurunuela in https://github.com/ME-ICA/tedana/pull/1209 tedana_report is more dynamically generated so that we can adjust which figures to include depending on the inputted parameters. This opens options for more useful reports that are better tuned to different use-cases.
• Rename variables by @tsalo in https://github.com/ME-ICA/tedana/pull/1145
• Changes to --tedpca option by @Lestropie in https://github.com/ME-ICA/tedana/pull/1066
• Fixing codecov automation by @handwerkerd in https://github.com/ME-ICA/tedana/pull/1196
• CircleCI testing fix by @handwerkerd in https://github.com/ME-ICA/tedana/pull/1201
• Returns CircleCI config to before version matrics to fix codecov by @handwerkerd in https://github.com/ME-ICA/tedana/pull/1202
• Change CircleCI versioning to use version matrices by @eurunuela in https://github.com/ME-ICA/tedana/pull/1190
• Enforce equal figure widths in HTML report and make them adjustable by window size by @eurunuela in https://github.com/ME-ICA/tedana/pull/1154
• Don't rerun ICA if robustICA was used and clean up integration tests by @handwerkerd in https://github.com/ME-ICA/tedana/pull/1213

Documentation

• Adding recommendations for n_robust_runs by @handwerkerd in https://github.com/ME-ICA/tedana/pull/1216
• Add external link to release notes by @tsalo in https://github.com/ME-ICA/tedana/pull/1137
• Very small typo fix in documentation by @smoia in https://github.com/ME-ICA/tedana/pull/1139
• docs: add katielamar as a contributor for code, design, and ideas by @allcontributors in https://github.com/ME-ICA/tedana/pull/1197
• docs: add marlyr as a contributor for code by @allcontributors in https://github.com/ME-ICA/tedana/pull/1210
• Add logging for tedana newsletter subscription information by @eurunuela in https://github.com/ME-ICA/tedana/pull/1199

Dependency versions

• Support Python 3.13 by @handwerkerd in https://github.com/ME-ICA/tedana/pull/1183
• update codecov to 5.3.0 by @handwerkerd in https://github.com/ME-ICA/tedana/pull/1193

New Contributors

• @katielamar made their first contribution in https://github.com/ME-ICA/tedana/pull/1177
• @marlyr made their first contribution in https://github.com/ME-ICA/tedana/pull/1208
• @Lestropie made their first contribution in https://github.com/ME-ICA/tedana/pull/1066

Full Changelog: https://github.com/ME-ICA/tedana/compare/24.0.2...25.0.0