Tedana

Release Notes

This release changes many internal aspects of the code, but there was a small bug that prevented it from building for `pip`. Since this version cannot be installed through `pip` the descriptive release notes are included with [Version 23.0.1](https://github.com/ME-ICA/tedana/releases/tag/23.0.1)

Changes

* [REF] Decision Tree Modularization (756) jbteves handwerkerd n-reddy marco7877 tsalo

**Full Changelog**: <https://github.com/ME-ICA/tedana/compare/0.0.13...23.0.0>

Release Notes

This is the last release before refactoring of large portions of the code.

Breaking Changes

* 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. (938)
* 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 the python API, but not from the command line. Now AIC is the default for both. (877)

Additional changes to highlight

* 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 so warnings from users not having duecredit installed will **finally** be gone (875)
* Tedana python package management now uses setup.cfg (874)

All changes since last stable release

* Generalize installation instructions to work with Windows in CONTRIBUTING by aryangupta701 in https://github.com/ME-ICA/tedana/pull/846
* [MAINT] Switch to setup.cfg-based configuration by tsalo in https://github.com/ME-ICA/tedana/pull/874
* [FIX] Add function to prep data for JSON serialization by jbteves in https://github.com/ME-ICA/tedana/pull/859
* [ENH, FIX] PCA variance enhancements and consistency improvements by handwerkerd in https://github.com/ME-ICA/tedana/pull/877
* Print optimal number of maPCA components and plot optimization curves by eurunuela in https://github.com/ME-ICA/tedana/pull/839
* [DOC] Add information about using tedana with fMRIPrep v21.0.0 by tsalo in https://github.com/ME-ICA/tedana/pull/847
* [REF] Replace duecredit with BibTeX by tsalo in https://github.com/ME-ICA/tedana/pull/875
* Update CONTRIBUTING.md by jbteves in https://github.com/ME-ICA/tedana/pull/885
* [REF] Suppresses divide by 0 warning by jbteves in https://github.com/ME-ICA/tedana/pull/786
* Add links to several multi-echo datasets by tsalo in https://github.com/ME-ICA/tedana/pull/895
* Add F-T2 and F-S0 maps to verbose outputs by tsalo in https://github.com/ME-ICA/tedana/pull/893
* [MAINT] Add 3.10 unit test, compatibilities in setup.cfg by jbteves in https://github.com/ME-ICA/tedana/pull/818
* [FIX] Use capital names in desc-ICAOrth_mixing.tsv columns by pablosmig in https://github.com/ME-ICA/tedana/pull/906
* [DOC] Add documentation page on denoising approaches by tsalo in https://github.com/ME-ICA/tedana/pull/823
* docs: add giadaan as a contributor for doc by allcontributors in https://github.com/ME-ICA/tedana/pull/916
* Add Nashiro dataset to documentation by Kasambx in https://github.com/ME-ICA/tedana/pull/912
* Fix example code in denoising documentation by tsalo in https://github.com/ME-ICA/tedana/pull/917
* Sorting varex for decision tree criterion I011 by handwerkerd in https://github.com/ME-ICA/tedana/pull/924
* [DOC] Remove Josh as maintainer by jbteves in https://github.com/ME-ICA/tedana/pull/928
* add pandas version check >= 1.5.2 and mod behavior by pmolfese in https://github.com/ME-ICA/tedana/pull/938

New Contributors
* aryangupta701 made their first contribution in https://github.com/ME-ICA/tedana/pull/846
* pablosmig made their first contribution in https://github.com/ME-ICA/tedana/pull/906
* Kasambx made their first contribution in https://github.com/ME-ICA/tedana/pull/912
* pmolfese made their first contribution in https://github.com/ME-ICA/tedana/pull/938

**Full Changelog**: https://github.com/ME-ICA/tedana/compare/0.0.12...0.0.13

Summary
This would ordinarily not have been released, but an issue with one of our dependencies means that people cannot install tedana right now. The most notable change (which will potentially change your results!) is that PCA is now defaulting to the "aic" criterion rather than the "mdl" criterion.

What's Changed
* [DOC] Add JOSS badges by tsalo in https://github.com/ME-ICA/tedana/pull/815
* [FIX] Fixes broken component figures in report when there are more than 99 components by manfredg in https://github.com/ME-ICA/tedana/pull/824
* [DOC] Add manfredg as a contributor for code by allcontributors in https://github.com/ME-ICA/tedana/pull/825
* DOC: Use RST link for ME-ICA by effigies in https://github.com/ME-ICA/tedana/pull/832
* [DOC] Fixing a bunch of warnings & rendering issues in the documentation by handwerkerd in https://github.com/ME-ICA/tedana/pull/840
* [DOC] Replace mentions of Gitter with Mattermost by tsalo in https://github.com/ME-ICA/tedana/pull/842
* [FIX] The rationale column of comptable gets updated when no manacc is given by eurunuela in https://github.com/ME-ICA/tedana/pull/855
* Made AIC the default maPCA option by eurunuela in https://github.com/ME-ICA/tedana/pull/849
* [DOC] Improve logging of component table-based manual classification by tsalo in https://github.com/ME-ICA/tedana/pull/852
* [FIX] Add jinja2 version pin as workaround by jbteves in https://github.com/ME-ICA/tedana/pull/870

New Contributors
* manfredg made their first contribution in https://github.com/ME-ICA/tedana/pull/824

**Full Changelog**: https://github.com/ME-ICA/tedana/compare/0.0.11...0.0.12

Release Notes

Tedana's 0.0.11 release includes a number of bug fixes and enhancements, and it's associated with publication of our Journal of Open Source Software (JOSS) paper! Beyond the JOSS paper, two major changes in this release are (1) outputs from the `tedana` and `t2smap` workflows are now BIDS compatible, and (2) we have overhauled how masking is performed in the `tedana` workflow, so that improved brain coverage is retained in the denoised data, while the necessary requirements for component classification are met.

🔧 Breaking changes

- The `tedana` and `t2smap` workflows now generate BIDS-compatible outputs, both in terms of file formats and file names.
- Within the `tedana` workflow, T2* estimation, optimal combination, and denoising are performed on a more liberal brain mask, while TE-dependence and component classification are performed on a reduced version of the mask, in order to retain the increased coverage made possible with multi-echo EPI.
- When running `tedana` on a user-provided mixing matrix, the order and signs of the components are no longer modified. This will not affect classification or the interactive reports, but the mixing matrix will be different.

✨ Enhancements

- `tedana` interactive reports now include carpet plots.
- The organization of the documentation site has been overhauled to be easier to navigate.
- We have added documentation about how to use `tedana` with fMRIPrep, along with a gist that should work on current versions of fMRIPrep.
- Metric calculation is now more modular, which will make it easier to debug and apply in other classification decision trees.

🐛 Bug fixes

- One component was not rendering in interactive reports, but this is fixed now.
- Inputs are now validated to ensure that multi-file inputs are not interpreted as single z-concatenated files.

Changes since last stable release

* [JOSS] Add accepted JOSS manuscript to `main` (813) tsalo
* [FIX] Check data type in `io.load_data` (802) tsalo
* [DOC] Fix link to developer guidelines in README (797) tsalo
* [FIX] Figures of components with index 0 get rendered now (793) eurunuela
* [DOC] Adds NIMH CMN video (792) jbteves
* [STY] Use `black` and `isort` to manage library code style (758) tsalo
* [DOC] Generalize preprocessing recommendations (769) tsalo
* [DOC] Add fMRIPrep collection information to FAQ (773) tsalo
* [DOC] Add link to EuskalIBUR dataset in documentation (780) tsalo
* [FIX] Add resources folder to package data (772) tsalo
* [ENH] Use different masking thresholds for denoising and classification (736) tsalo
* [DOC, MAINT] Updated dependency version numbers (763) handwerkerd
* [REF] Move logger management to new functions (750) tsalo
* [FIX] Ignore non-significant kappa elbow when no non-significant kappa values exist (760) tsalo
* [ENH] Coerce images to 32-bit (759) jbteves
* [ENH] Add carpet plot to outputs (696) tsalo
* [FIX] Correct manacc documentation and check for associated inputs (754) tsalo
* [DOC] Reorganize documentation (740) tsalo
* [REF] Do not modify mixing matrix with sign-flipping (749) tsalo
* [REF] Eliminate component sorting from metric calculation (741) tsalo
* [FIX] Update apt in CircleCI (746) notZaki
* [DOC] Update resource page with dataset and link to Dash app visualizations (745) jsheunis
* [DOC] Clarify communication pathways (742) tsalo
* [FIX] Disable report logging during ICA restart loop (743) tsalo
* [REF] Replace metric dependency dictionaries with json file (739) tsalo
* [FIX] Add references back into the HTML report (737) tsalo
* [ENH] Allows iterative clustering (732) jbteves
* [REF] Modularize metric calculation (591) tsalo
* Rename sphinx functions to fix building error for docs (727) eurunuela
* [ENH] Generate BIDS Derivatives-compatible outputs (691) tsalo

Release Notes

We have made this release candidate to test recent enhancements. Please open issues if you experience any problems.

Changes

* [DOC] Add link to EuskalIBUR dataset in documentation (780) tsalo
* [FIX] Add resources folder to package data (772) tsalo
* [ENH] Use different masking thresholds for denoising and classification (736) tsalo
* [DOC, MAINT] Updated dependency version numbers (763) handwerkerd
* [REF] Move logger management to new functions (750) tsalo
* [FIX] Ignore non-significant kappa elbow when no non-significant kappa values exist (760) tsalo
* [ENH] Coerce images to 32-bit (759) jbteves
* [ENH] Add carpet plot to outputs (696) tsalo
* [FIX] Correct manacc documentation and check for associated inputs (754) tsalo
* [DOC] Reorganize documentation (740) tsalo
* [REF] Do not modify mixing matrix with sign-flipping (749) tsalo
* [REF] Eliminate component sorting from metric calculation (741) tsalo
* [FIX] Update apt in CircleCI (746) notZaki
* [DOC] Update resource page with dataset and link to Dash app visualizations (745) jsheunis
* [DOC] Clarify communication pathways (742) tsalo
* [FIX] Disable report logging during ICA restart loop (743) tsalo
* [REF] Replace metric dependency dictionaries with json file (739) tsalo
* [FIX] Add references back into the HTML report (737) tsalo
* [ENH] Allows iterative clustering (732) jbteves
* [REF] Modularize metric calculation (591) tsalo
* Rename sphinx functions to fix building error for docs (727) eurunuela
* [ENH] Generate BIDS Derivatives-compatible outputs (691) tsalo

Release Notes

The 0.0.10 release of tedana includes a number of bug fixes over the previous stable release, and drops support for Python 3.5, as well as adding formal support for Python 3.8 and 3.9.
As always, we encourage users to review our documentation (at tedana.readthedocs.io) which includes information for theoretical background for multi-echo, acquisition-related guidance, and documentation for our :sparkles: interactive reports. :sparkles:

The complete changelog since the last alpha release is included below. Here, we briefly summarize the significant changes since our last stable release.

:wrench: Breaking changes
- PCA is now normalized over time, which may change number of PCA components retained
- A bug-fix for ICA f-statistic thresholding may change some component classifications and metric calculations.
- For datasets with more than 3 echoes, a bug was fixed where we required all echoes to be "good" instead of just the minimum three needed for accurate metric calculation. This may significantly impact classifications on datasets with more than 3 echoes.

:sparkles: Enhancements
- Formal support added for Python 3.8 and 3.9.
- We now normalize PCA over time.

:bug: Bug fixes
- In prior releases, f-statistic maps were thresholded just before kappa/rho calculation, such that the metric maps related to T2 and S0 were not aligned with the values used to calculate kappa and rho. All T2 and S0 maps are now thresholded at calculation, so that their derivative metrics reflect this thresholding as well.
- In previous releases, there was a bug where datasets required all echoes be considered "good" for a voxel to be included in denoising. However, in datasets with more than three echoes, this is too conservative. This release requires only the minimal 3 echoes in order to perform accurate metric calculations.

Changes since last stable release

* [MAINT] Modifies actions to run on release publish (725) jbteves
* [DOC] Add warning about not using release-drafter releases to developer instructions (718) tsalo
* [FIX] Bumps (down) sklearn and scipy (723) emdupre
* [MAINT] Drop 3.5 support and begin 3.8 and 3.9 support (721) tsalo
* [FIX] Calculate Kappa and Rho on full F-statistic maps (714) tsalo
* [FIX] Adds f_max to right place (712) jbteves
* [DOC] Added MAPCA to list of dependencies (709) handwerkerd
* [DOC] Add references to HTML report (695) tsalo
* [FIX] Enable normalization in mapca call (705) notZaki
* [REF] Replace MAPCA code with mapca library (641) tsalo
* [REF] Normalize over time in MAPCA (702) tsalo
* [ENH] Match BokehJS with BokehPy version (703) notZaki
* [MAINT] Update Kirstie affiliation in zenodo file (694) KirstieJane
* [MAINT] Add Javier Gonzalez-Castillo to Zenodo file (682) javiergcas
* [DOC] Harmonizes Governance Documents (678) jbteves