Refer to unstandardized PEs as PEs and standardized PEs as betas

[tsalo]

Closes #1309.

Changes proposed in this pull request:

• Consistently refer to unstandardized parameter estimates (which we'd been calling "betas") as "PEs", "pes", "parameter estimates", or "unstandardized parameter estimates".
• Consistently refer to standardized parameter estimates (with which we'd recently replaced our Fisher's Z-transformed standardized parameter estimates [see Replace pseudo-z-statistics with standardized parameter estimates #1332] and had been calling "weights" or "Z-statistic maps") as "betas" or "standardized parameter estimates".
• Remove the now-unused (as of Replace pseudo-z-statistics with standardized parameter estimates #1332) calculate_z_maps function.

As a result, a number of metrics have been renamed:

• "map Z": "map optcom standardized parameter estimates"
• "map Z clusterized": "map optcom standardized parameter estimates clusterized"
• "map weight": "map optcom standardized parameter estimates"
• "map weight clusterized": "map optcom standardized parameter estimates clusterized"
• "map optcom betas": "map optcom parameter estimates"
• "map echo betas": "map echo parameter estimates"
• "map beta T2 clusterized": "map PE T2 clusterized"
• "map beta S0 clusterized": "map PE S0 clusterized"

[codecov]

Codecov Report

❌ Patch coverage is 91.95402% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.20%. Comparing base (cd3cc54) to head (5674605).
⚠️ Report is 7 commits behind head on main.

Files with missing lines	Patch %	Lines
tedana/metrics/collect.py	76.19%	1 Missing and 4 partials ⚠️
tedana/workflows/ica_reclassify.py	0.00%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1338      +/-   ##
==========================================
- Coverage   90.21%   90.20%   -0.02%     
==========================================
  Files          30       30              
  Lines        4867     4861       -6     
  Branches      820      820              
==========================================
- Hits         4391     4385       -6     
  Misses        316      316              
  Partials      160      160              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

This PR standardizes terminology around parameter estimates: unstandardized estimates are now referred to as PEs, and standardized estimates as betas/standardized parameter estimates, across code, metrics, tests, and documentation. It also removes the obsolete calculate_z_maps path in favor of directly using standardized parameter estimates and updates configuration/metadata and deprecation handling for old metric names.

Changes:

• Renamed functions, variables, metrics, and tests to distinguish unstandardized parameter estimates (PEs) from standardized parameter estimates (betas), including calculate_weights → calculate_standardized_parameter_estimates and calculate_betas → calculate_unstandardized_parameter_estimates.
• Updated dependence metrics and collections to use beta_maps (standardized parameter estimates) instead of z_maps/“weights” and adjusted metrics.json plus the dependency resolver to deprecate old metric labels (e.g., "map weight", "map optcom betas") in favor of new names.
• Cleaned up reporting and documentation (static figures, outputs, denoising, dependence metrics, and approach docs) so user-facing descriptions match the new PE/beta nomenclature, while removing the now-unused calculate_z_maps function and its tests.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tedana/workflows/tedana.py	Renames comments and internal regression coefficients from “betas” to PEs in the main workflow and orthogonalization step, aligning terminology without changing behavior.
tedana/workflows/ica_reclassify.py	Mirrors the orthogonalization coefficient rename from “betas” to PEs during reclassification, maintaining consistent math.
tedana/tests/test_stats.py	Updates get_coeffs and fit_model tests to expect PEs instead of betas while preserving numerical checks and shapes.
tedana/tests/test_metrics_dependence.py	Removes tests for the deleted calculate_z_maps and rewrites dependence metrics tests to use beta_maps and PE terminology.
tedana/tests/test_metrics.py	Adds/updates smoke tests for the new calculate_standardized_parameter_estimates and calculate_unstandardized_parameter_estimates, and switches all dependence tests from z_maps to beta_maps and from betas to PEs where appropriate.
tedana/stats.py	Changes get_coeffs and fit_model docstrings/locals from betas to PEs without altering the underlying least-squares computation; tests confirm behavior.
tedana/resources/config/metrics.json	Renames metric keys and dependencies (e.g., "map weight" → "map optcom standardized parameter estimates", "map optcom betas" → "map optcom parameter estimates", "map beta T2 clusterized" → "map PE T2 clusterized"), keeping the dependency graph consistent with the new naming.
tedana/reporting/static_figures.py	Adjusts comments and docstrings to refer to PEs instead of betas for component maps and recomputed images used in static reports.
tedana/metrics/external.py	Renames fit coefficients from betas to PEs in fit_model_with_stats and fit_mixing_to_regressors, updating docstrings while leaving F/R² computation unchanged.
tedana/metrics/dependence.py	Introduces calculate_standardized_parameter_estimates/calculate_unstandardized_parameter_estimates, removes calculate_z_maps, rewrites F-map and dependence calculations to operate on PEs/betas, and switches signal-vs-noise helpers to beta_maps/beta_clmaps.
tedana/metrics/collect.py	Changes default and required metric names, uses the new dependence functions, rewires kappa/rho, variance explained, Dice, signal-noise, PSC, and clusterized maps to the renamed metrics, and updates metadata text for PE-based maps.
tedana/metrics/_utils.py	Extends deprecated_metrics to reject legacy metric labels (e.g., "map weight", "map optcom betas") with guidance to the new names, and refreshes determine_signs docstrings to speak in terms of parameter estimates.
tedana/io.py	Renames internal regression coefficients to PEs in denoising and mixing-reconstruction routines, and clarifies naming for z-scored component maps while preserving I/O behavior.
tedana/gscontrol.py	Renames regression coefficients from betas to PEs in global signal regression while keeping the same linear algebra and variance-explained computation.
tedana/decay.py	Renames log-linear regression coefficients from betas to PEs in T2*/S0 estimation, with unchanged numerical logic.
docs/outputs.rst	Updates the description of the component spatial map from “beta map” to “PE map” and its text to talk about parameter estimates (with a small spelling issue noted).
docs/dependence_metrics.rst	Clarifies that TEDPCA/TEDICA uses raw PEs (not standardized betas) in the dependence models, matching the new code path.
docs/denoising.rst	Adjusts example code snippets to use pes and “parameter estimates” instead of betas, aligning denoising recipes with the code changes.
docs/approach.rst	Revises description of how parameter estimates are used for reconstruction and TE-(in)dependence modeling to use the PE terminology, including the explanation figure caption.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[tsalo]

Some things will only make sense once #1337 is merged, so I'll hold off on requesting reviews until that's done.

[Copilot]

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 4 comments.

Comments suppressed due to low confidence (1)

tedana/metrics/external.py:405

• This commented-out TODO block references pes_full, but the return value from fit_model_with_stats is currently discarded (_ = ...). Either capture the returned parameter estimates if you intend to save them, or remove/update this TODO so it doesn't reference an undefined variable. Also, fix the typo in exte rnal_regressors inside the comment to avoid confusion if this code is ever re-enabled.

    # TODO pes_full_model are the fits to all external regressors and might be useful to save
    # TODO Also consider saving regressor_models or the detrending regressors
    # pes_full_model = pd.DataFrame(
    #     data=pes_full.T,
    #     columns=np.concatenate(
    #         (np.array(detrend_regressors.columns), np.array(exte rnal_regressors.columns))
    #     ),
    # )

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.