Supply source disaggregation, irrigation conveyance, and feature enhancements

[hassaniazi]

This pull request introduces several new features, dependency updates, and improvements to documentation and CI workflows for the Tethys project. The most significant changes are the addition of source disaggregation and irrigation conveyance efficiency options to the model, enhancements to temporal downscaling configuration, and updates to dependencies and installation instructions. Below are the most important changes, grouped by theme.

New Features and Model Enhancements:

• Added support for source disaggregation (runoff, groundwater, desalination) and irrigation conveyance efficiency in the Tethys model, with corresponding configuration options and documentation updates. This includes new attributes, logic in run_model, and YAML config documentation. [1] [2] [3] [4] [5] [6] [7]
• Improved temporal downscaling configuration: added normalization of temporal config, support for legacy and new formats, and enhanced file path resolution. [1] [2]
• Added an option to fully override filters in easy_query via a new replace_filters argument. [1] [2]
• Added a new utility function extract_resource_name for cleaning resource names.

Dependency and Installation Updates:

• Updated required and development dependencies in setup.py, including pinning specific versions for better reproducibility and updating the install instructions to use the correct package name (tethys-downscaling). [1] [2] [3] [4]
• Updated the author list in both setup.py and documentation. [1] [2]
• Bumped the project version to 2.2.0.

Documentation Improvements:

• Expanded and clarified the configuration file documentation, including new options and improved formatting for the user guide. [1] [2] [3]
• Updated installation instructions and prerequisites in both the README and getting started guide. [1] [2]

Continuous Integration and Workflow Updates:

• Updated GitHub Actions workflows: improved build matrix to test against Python 3.9 and 3.11, updated actions versions, and enhanced dependency installation for development and testing.
• Refined the paper build workflow to trigger only on main branch for push and pull requests, and updated artifact upload action version. [1] [2]

These changes collectively improve the flexibility, reproducibility, and usability of the Tethys package for both users and developers.

[Copilot]

Pull request overview

This pull request expands the Tethys downscaling model with new configuration options and capabilities (notably source disaggregation and irrigation conveyance efficiency), while also modernizing temporal downscaling configuration, updating dependencies, and refreshing docs/CI for improved reproducibility and testing.

Changes:

• Add source disaggregation utilities + model integration and document new YAML options (source disaggregation, irrigation conveyance efficiency).
• Normalize/modernize temporal downscaling configuration and update temporal method call patterns.
• Update packaging/dependencies, installation docs, and GitHub Actions workflows (incl. Python matrix + dev extras for testing).

Reviewed changes

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

Show a summary per file

File	Description
tethys/utils/source_disaggregation.py	New GCAM-query-based source share calculation and gridded share generation utilities.
tethys/utils/region_to_id_mapping.py	Add basin-name mapping dictionaries used for basin/resource normalization.
tethys/utils/install_supplement.py	Update data supplement lookup to match the distribution name/versioning.
tethys/tdmethods/weights.py	Allow temporal_distribution() to be invoked with a model object / normalized config.
tethys/tdmethods/irrigation.py	Same as above for irrigation temporal downscaling.
tethys/tdmethods/electricity.py	Same as above for electricity temporal downscaling.
tethys/tdmethods/domestic.py	Same as above for domestic/municipal temporal downscaling.
tethys/model.py	Add source disaggregation workflow, irrigation efficiency adjustment, and temporal config normalization/path resolution.
tethys/datareader/regional.py	Add extract_resource_name() helper for GCAM resource name cleanup.
tethys/datareader/easy_query.py	Add replace_filters option to fully override default query filters.
tethys/__init__.py	Bump package version to 2.2.0.
setup.py	Update authors and dependency pins/extras (incl. pytest/coverage in dev extras).
requirements.txt	Update dependency floor versions and include distributed / setuptools<81.
README.md	Fix install command to tethys-downscaling.
docs/source/user_guide.rst	Document new config options and improve config table formatting.
docs/source/getting_started.rst	Fix install command to tethys-downscaling.
docs/source/conf.py	Update documentation author list.
.github/workflows/paper.yml	Restrict triggers to main and modernize artifact upload action.
.github/workflows/build.yml	Add Python 3.9/3.11 matrix and install dev extras for tests/coverage.

---

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