26.0.0

[handwerkerd]

What's Changed

🛠 Breaking Changes

• Rescale normalized variance explained to 0 - 100 by @tsalo in Rescale normalized variance explained to 0 - 100 #1310
  • The relationship between variance explained and normalized variance explained explained is better documented.
  • An ongoing confusion was that varianced explained was a percentile from 0-100% while
    normalized varianced explained was a ratio from 0-1.
    The breaking change is that both are now percentages from 0-100%
• Replace pseudo-z-statistics with standardized parameter estimates by @tsalo in Replace pseudo-z-statistics with standardized parameter estimates #1332
  • Tedana previously generated "z-statistic maps" by calculating standardized parameter estimates, cropping them to between -0.999 and 0.999, Fisher's z-transforming them, then z-scoring them, and finally cropping them once again to -8 to 8. We have replaced this convoluted, statistically invalid metric with standardized parameter estimates.
  • We have also replaced the z-statistic threshold that was being applied to the pseudo-z-statistic maps (1.96; p < 0.05 two-sided) with a proportional threshold of 5%. As a result, the metrics 'kappa', 'rho', 'signal-noise_z', 'signal-noise_t', 'signal-noise_p', and 'countnoise' may change slightly.

User Facing New Features

• Added arrow keys for report visualization and improved static mask by @handwerkerd and @mauspad in Added arrow keys for report visualization and improved static mask #1333
  • Possibly the most requested feature!
    When viewing the html report, after clicking to view a component,
    one can use the left and right arrow keys to cycle through neighboring components on the variance explained pie chart.
  • Also adds total variance explained for accepted and rejected components into the center of the pie chart
  • Improves coloring for the adaptive mask visualization so that it's more clear which voxels in the provided mask
    are removed for not having 1 or 3 good echoes.
• Add Rica integration for interactive ICA component visualization by @eurunuela in Add Rica integration for interactive ICA component visualization #1288
  • There is now a RICA button in the html report.
    Clicking the button shows command-line text to use to run the RICA version of the report.
    The RICA report has more interactive features and can be used to manual inspect and change component classifications.
  • With this addition users will be able to use RICA without needing to upload data to a public website (though the data is never uploaded to any server, it stays local to your machine/browser) or
    separately install it and set up a server.

New outputted information or options for outputing more information

• Track decay model fit failures by @tsalo in Track decay model fit failures #1282
  • When T2* maps are calculated with the non-linear curvefit option, the estimation sometimes fails
    The total number of voxels with failed estimates were previously saved,
    and now a map of which voxels have estimation failures is also saved.
  • Note: Previous functionality is retained in that the log-linear fit is used for voxels were curvefit fails
• Write out T2* & S0 variance + T2*-S0 covariance by @tsalo in Write out T2* & S0 variance + T2*-S0 covariance #1290
  • Retains variance and covariance estimates from nonlinear curve fit of T2* and S0 when using --fittype curvefit and --verbose
  • Additional under-the-hood changes for these calculations
• Document metrics in more detail by @tsalo in Document metrics in more detail #1303
  • Many of the added metrics in the following PRs hvae explanations documented in https://tedana.readthedocs.io/en/stable/dependence_metrics.html#other-available-metrics
• Add Kappa-Rho difference metric by @tsalo in Add Kappa-Rho difference metric #1284
  • If "kappa_rho_difference" is defined in a decision tree, this additional metric will be calculated.
    It is abs(kappa-rho)/(kappa+rho) and is designed to be a measure of how "purely" kappa or rho a component is.
• Add external regressor correlation data to metrics file by @eurunuela in Add external regressor correlation data to metrics file #1297
  • A color map of the fit of external regressors to the component time series was previously added to the html report, but the actual values were not saved. Now the correlations are saved in the component table.
  • Note: This is a slightly different value than the one visualized in the report since the report detrends the data first.
    We may harmonize these two measures in a future release so that detrending is consisently used.
• Add metrics for common measures of explained variance by @tsalo in Add metrics for common measures of explained variance #1311
  • Added additional metrics for variance explained that vary based on whether it's how much each components
    time series explains the variance or how much a time series explains variance in relation to other components.
    These are not currently being used in any decision tree, but may be useful for futrue testing and comparisions.
• Add option to calculate valid univariate z statistics in decision tree by @tsalo in Add option to calculate valid univariate z statistics in decision tree #1328
  • A few different options for calculating the z statistic maps were added.
    These are not currently being used in any decision tree, but may be useful for future testing and comparisons.
• Generalize the generate_decision_table_score function by @tsalo in Generalize the generate_decision_table_score function #1351
  • The decision_table_score is a ranking that combined multiple metrics.
    This generalizes that ranking so that it can be used to rank user-defined measures instead of a hard-coded list.

👎 Future Deprecation

• Deprecate support for z-concatenated inputs by @handwerkerd in Deprecate support for z-concatenated inputs #1319
  • Added a warning that we will deprecate support for z-concatenated intputs in 2027.
    We think this is a legacy option that no one uses any more.
    If you are still using z-concatenated files and want us to retain this feature, please comment on this issue ASAP

🐛 Bug Fixes

• Fix check of dummy scans against external regressors by @tsalo in Fix check of dummy scans against external regressors #1273
• fixing a pandas string to bool issue by @handwerkerd and @marlyr in fixing a pandas string to bool issue #1340
• Fix handling of op3 in dec_left_op_right by @tsalo in Fix handling of op3 in dec_left_op_right #1348
  • This is a bug that in a decision tree function.
    The only distributed decision tree this affected is demo_external_regressors_motion_task_models.
    If you are using that decision tree, this will alter your results.
• Avoid error on non-inf correlations when generating plots by @miltoncamacho in Avoid error on non-inf correlations when generating plots #1335
  • Prevents tedana from crashing when the correlations from the external regressors to the components results in non-finite values.
• Set zooms in reference image by @tsalo in Set zooms in reference image #1373
  • Fixes a bug induced by Update numpy requirement from <=1.26.3,>=1.16 to >=1.16,<=1.26.4 #1035 where the TR was no longer being properly saved when writing out data
• account for user-provided nonbinary masks by @handwerkerd and @tsalo in account for user-provided nonbinary masks #1371
  • Restores functionality that was removed by Update numpy requirement from <=1.26.3,>=1.16 to >=1.16,<=1.26.4 #1035 where, if a user provides a mask with multiple non-zero values, all values greater than 0 will be considered part of the mask.
• fix: Add cache-control for data files and improve Rica modal accessibility by @eurunuela in fix: Add cache-control for data files and improve Rica modal accessibility #1327
  • Fixes a bug with the recently implementation of RICA from tedana (Add Rica integration for interactive ICA component visualization #1288)

🎉 Under-the-hood New Features

• Operate entirely on masked data by @tsalo in Operate entirely on masked data #1305
  • This is the most substantial under-the-hood new feature
  • tedana previously ran calculations on matrices with all voxels.
    Now most arrays in the code will just include voxels within the mask.
  • This change does not seem to affect processing speed much, but it substantially reduces tedana's memory usage.
• Add comprehensive tests for metric calculations by @eurunuela in Add comprehensive tests for metric calculations #1304
  • Existing and new metrics are now tested for numerical consistency as part of integration testing
• Add auto-detection of T2* map and echo time units by @eurunuela in Add auto-detection of T2* map and echo time units #1287
  • Units for T2* are consistently outputted in seconds
  • Future deprecation warning added if echo times are entered in milliseconds
• Parallelize nonlinear T2*/S0 estimation and RobustICA by @tsalo in Parallelize nonlinear T2*/S0 estimation and RobustICA #1266
• Remove unused z_maps parameter in calculate_f_maps by @tsalo in Remove unused z_maps parameter in calculate_f_maps #1334
• Remove unnecessary variance normalization steps by @tsalo in Remove unnecessary variance normalization steps #1339
• Remove maximum version restriction for nilearn by @tsalo in Remove maximum version restriction for nilearn #1262
• Change n_iter to max_iter in TSNE parameters by @miltoncamacho in Change n_iter to max_iter in TSNE parameters #1276
• Fix interpolation arg in percentile numpy class by @miltoncamacho in Fix interpolation arg in percentile numpy class  #1293
• Consolidate gscontrol plots by @tsalo in Consolidate gscontrol plots #1298
• Add store_artifacts steps to integration test jobs by @eurunuela in Add store_artifacts steps to integration test jobs #1318
• docs: add mauspad as a contributor for code by @allcontributors[bot] in docs: add mauspad as a contributor for code #1366
• chore: Use tox-uv and uv.lock to test minimum, locked, and pre-release dependencies by @effigies in chore: Use tox-uv and uv.lock to test minimum, locked, and pre-release dependencies #1229
  • This issue and the following issues are part of trying to imoprove/fix issues with version checks on dependencies and successfully running continuious integration with CircleCI
• chore: uv lock --upgrade by @effigies in chore: uv lock --upgrade #1316
• chore(deps): Set cooldown for dependabot by @effigies in chore(deps): Set cooldown for dependabot #1322
• Switch pkg_resources to importlib by @tsalo in Switch pkg_resources to importlib #1363
• Possible fix for CircleCI testing file download problem by @handwerkerd in Possible fix for CircleCI testing file download problem #1367

New Contributors

• @miltoncamacho made their first contribution in Change n_iter to max_iter in TSNE parameters #1276
• @mauspad made their first contribution in Added arrow keys for report visualization and improved static mask #1333

Full Changelog: 25.1.0...26.0.0

---

This discussion was created from the release 26.0.0.