Tedana

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

Release Notes

The 0.0.9 release of tedana includes a large number of changes over the previous stable release.
This release contains a number of breaking, fixing, and useful changes. As always, we encourage users to review our documentation (at tedana.readthedocs.io) which now includes more information theoretical background for multi-echo, acquisition-related guidance, and documentation for our :sparkles: new 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
- We have updated our adaptive mask calculation between the t2smap and tedana workflows. t2smap will now use all voxels that have signal in at least one echo in the optimal combination, while tedana will use those voxels that have signal in at least three echos and so can be used in echo-dependent denoising. This change will facilitate integration into larger processing workflows such as fMRIPrep.
- We have added an internal check for whether any BOLD components are identified and--if not--set the ICA to automatically re-run for a limited number of iterations.
- Log files are now by datetime, allowing multiple runs to have systematic naming.
- Filenames for decomposition and metric maps are now BIDS derivative-compatible. Please see documentation for the full list of new filenames.
- Component tables are now in .json format.
- Changed tab-separated files from .txt to .tsv file extension.
- The --sourceTEs option has been removed.
- T2* maps are now in seconds rather than milliseconds.
- The --tedpca mle option has been removed.
- The --gscontrol option "T1c" is now "mir" for minimum image regression.
- For the "--manacc" option, you should supply a list of integers instead of a comma-separated string.

:sparkles: Enhancements
- We have introduced interactive reports for better accessing and understanding component classification. A guide to interpreting the new reports is available here: https://tedana.readthedocs.io/en/latest/reporting.html
- A previously collected quantitative T2* map (in seconds) can now optionally be supplied directly. If provided, this information will be used to guide the optimal combination, rather than estimating the T2* map directly from the echo data.
- Files are now gzipped by default to save disk space.
- Adds the --out_dir argument to t2smap workflow to choose what directory files are written to.
- The t2smap workflow is now fmriprep compatible.

:bug: Bug fixes
- The default PCA method has been updated to follow Calhoun et al. (2001, Hum. Brain Map.). This avoids a known error where too many PCA components would be selected.
- We have added a flooring procedure for T2* map calculations to prevent divide-by-zero errors during optimal combination.
- Environments are not coerced to single-threaded computation after calling tedana.
- Fixed variance-explained outlier detection problem where first value was always NaN and variance explained was always negative.
- Fixed component table loading bug that resulted from unexpected pandas behavior.
- Fixed bug where the wrong number of echoes would be allocated in-program.
- Fixed bug where only selecting one component would cause an error.
- Correctly incorporate user-supplied masks in T2* workflow.
- Fixed bug in PAID combination where mean of data would be used instead of SNR.

Changes since last alpha release

- [MAINT] Support Windows' paths; Update zenodo & contributor count (672) notZaki
- [FIX] Normalize data to zero mean and unit variance before dimension estimation (636) notZaki
- Move long description logic from info.py to setup.py (670) notZaki
- [MAINT] Add new contributors to Zenodo file (671) tsalo
- [DOC] Starts contribution page (624) jbteves
- [REF] Replaces master with main where possible (667) jbteves
- [ENH] Allow tedpca argument to be a float inside a string (665) notZaki
- [ENH] Add ability to re-run ICA when no BOLD components are found (663) tsalo
- [ENH] Add threshold argument to make_adaptive_mask (635) tsalo
- [REF] Replace deprecated get_data with get_fdata (664) notZaki
- docs: add notZaki as a contributor (661) allcontributors
- [DOC] Clarify role of components in docs (660) notZaki
- [ENH] Implement variance explained threshold-based PCA option (658) tsalo
- [DOC] Log count of floored voxels in T2* estimation (656) tsalo
- [DOC] Add NeuroStars question link (651) tsalo
- [FIX] Eliminate duplicate lines in logs (645) tsalo
- [DOC] Add docstring to fit_loglinear (646) tsalo
- [FIX] Show logs in re-runs (637) notZaki
- [DOC] Governance update (615) handwerkerd
- docs: add notZaki as a contributor (630) allcontributors
- [TST] Allow CI for all-contributors (627) jbteves
- [ENH] Add diagonal reference line to kappa/rho plot (625) notZaki
- [MAINT] Add all contributors to Zenodo file (614) tsalo
- docs: add smoia as a contributor (616) allcontributors
- [REF] Rename T1c to "minimum image regression" (609) tsalo
- [DOC] Reporting documentation (465) javiergcas
- [DOC] Rewrite new PCA section (613) eurunuela
- docs: add aykhojandi as a contributor (610) allcontributors
- [DOC] Added link for tedana NeuroStars tag. (608) aykhojandi
- [DOC] Miscellaneous improvements to documentation (575) tsalo
- [ENH] Use list of ints for manacc instead of comma-separated string (598) tsalo
- [DOC] Use README as long_desc (595) emdupre
- [MAINT] Add workflow to autodeploy to PyPi (568) tsalo
- [TST] Show logging output during integration tests (588) tsalo
- [FIX] Add non-zero floor to T2* values (585) tsalo
- docs: add mvaziri as a contributor (587) allcontributors
- [DOC] Include [all] in developer setup install guidelines (572) tsalo
- [DOC] multi-echo reports (457) emdupre
- docs: add mjversluis as a contributor (580) allcontributors
- Update acquisition.rst to include information for Philips scanners (579) mjversluis