feat: Add T2 attribution module for diagnosing temperature changes #918
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
🤖 I've automatically formatted the code in this PR using:
Please pull the latest changes before making further edits. |
1 similar comment
|
🤖 I've automatically formatted the code in this PR using:
Please pull the latest changes before making further edits. |
sunt05
force-pushed
the
feat/t2-attribution-module
branch
from
643db7d to
e42529e
Compare
|
🤖 I've automatically formatted the code in this PR using:
Please pull the latest changes before making further edits. |
sunt05
force-pushed
the
feat/t2-attribution-module
branch
from
a205020 to
b9b11d7
Compare
Add a new diagnostic module that decomposes near-surface temperature differences between scenarios into physically attributable components using Shapley value decomposition. Features: - attribute_t2(): Compare two scenarios, decompose delta-T2 into flux, resistance, and air property contributions - diagnose_t2(): Automatic anomaly detection with methods: 'anomaly', 'extreme', 'diurnal' - AttributionResult class with plot() method (bar, diurnal, line, heatmap) - Hierarchical flux breakdown into Q*, QE, dQS, QF components - Exact closure guaranteed by Shapley decomposition Use cases: - Debug unexpected T2 values in simulations - Understand why green infrastructure cools cities - Quantify physical mechanisms driving temperature changes 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Co-authored-by: sunt05 <1802656+sunt05@users.noreply.github.com>
Add multi-variable attribution capability following the same Shapley decomposition framework used for T2. The q2 (2m specific humidity) attribution uses latent heat flux (QE) and the scale factor gamma = 1/(rho*Lv) to decompose humidity differences into physical mechanisms. New functions: - attribute_q2(): Decompose q2 differences between two scenarios - diagnose_q2(): Automatic anomaly detection for humidity - attribute(): Generic dispatcher for T2/q2 - diagnose(): Generic dispatcher for T2/q2 - _cal_gamma_humidity(): Scale factor for latent heat - _cal_r_eff_humidity(): Back-calculate moisture resistance The design maximises code reuse - both T2 and q2 follow the same flux-gradient physics pattern (X = X_ref + r * F * gamma). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Co-authored-by: sunt05 <1802656+sunt05@users.noreply.github.com>
Include the new attribution module in the meson build system. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
- Add comprehensive test suite for T2/q2 attribution functions - Improve error handling with numpy errstate for division operations - Add input validation for required DataFrame columns - Add warnings when forcing data not provided (affects accuracy) - Add warnings when significant data loss during index alignment - Add logging for low-flux timesteps producing NaN values - Improve docstrings with mathematical references (Owen 1972) - Fix Celsius to Kelvin conversion (273.16 -> 273.15) - Fix British English spelling in tutorial documentation
Restructure _attribution.py into _attribution/ package with separate modules for better maintainability. Add wind speed (U10) attribution alongside existing T2 and Q2 support. Co-Authored-By: Claude <noreply@anthropic.com>
sunt05
force-pushed
the
feat/t2-attribution-module
branch
from
525ea60 to
833d7dd
Compare
Co-authored-by: sunt05 <1802656+sunt05@users.noreply.github.com>
|
🤖 I've automatically formatted the code in this PR using:
Please pull the latest changes before making further edits. |
Update test imports to reflect the refactored attribution module which is now organised as a package with separate submodules for core Shapley functions, physics calculations, and helper utilities. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Add a new diagnostic module that decomposes near-surface temperature (T2) differences between scenarios into physically attributable components using Shapley value decomposition.
Key Features
attribute_t2(): Compare two SUEWS scenarios, decompose ΔT2 into:diagnose_t2(): Automatic anomaly detection for single-run debugging:'anomaly': Detect timesteps > N σ from daily mean'extreme': Compare top/bottom 5% vs. middle 50%'diurnal': Compare afternoon peak vs. morning baselineAttributionResultclass with:__repr__showing percentagesplot()method with 4 visualisation modes: bar, diurnal, line, heatmapto_dataframe()for further analysisMathematical Foundation
Uses exact Shapley decomposition for the triple product T2 = r × QH × γ:
Use Cases
Files Changed
src/supy/util/_attribution.pysrc/supy/util/__init__.pydocs/source/tutorials/python/attribution-tutorial.ipynbdocs/source/tutorials/python/tutorial.rstTest plan
__repr__generates formatted output🤖 Generated with Claude Code