Feature/area as input to spatial

[EddyCMWF]

Description

Contributor Declaration

By opening this pull request, I affirm the following:

• All authors agree to the Contributor License Agreement.
• The code follows the project's coding standards.
• I have performed self-review and added comments where needed.
• I have added or updated tests to verify that my changes are effective and functional.
• I have run all existing tests and confirmed they pass.

[Copilot]

Pull request overview

Adds support for passing a simple bounding-box area dictionary into the spatial aggregation APIs, allowing users to call spatial.mask/spatial.reduce without constructing a GeoDataFrame manually.

Changes:

• Introduces an area→GeoDataFrame conversion helper and decorator to wire area= into spatial.mask and spatial.reduce.
• Adds unit tests for area= behavior and mutual-exclusion rules with geodataframe.
• Updates spatial how-to docs and concepts documentation to describe and demonstrate area= usage.

Reviewed changes

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

Show a summary per file

File	Description
src/earthkit/transforms/spatial/_aggregate.py	Adds _area_to_geodataframe and a decorator to translate area= into geodataframe= for mask/reduce.
tests/test_30_spatial.py	Adds test coverage for area= conversions, masking/reduction behavior, and argument validation.
docs/source/how-tos/spatial/index.rst	Updates the spatial how-to toctree to include new/renamed notebooks.
docs/source/how-tos/spatial/howto_spatial_mean_era5_geometry.ipynb	Adds a notebook demonstrating the area= (bounding box) workflow.
docs/source/how-tos/spatial/howto_spatial_mean_era5_area.ipynb	Updates the geometry-based spatial-mean notebook title/intro.
docs/source/concepts/spatial.rst	Documents area= as an alternative to geodataframe for mask/reduce.

---

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

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (1)

src/earthkit/transforms/spatial/_aggregate.py:351

• When area is provided alongside mask_arrays (e.g. reduce(..., mask_arrays=..., area=...)), the decorator converts area into an implicit geodataframe, causing the later assertion to fail with "Either a geodataframe or mask arrays must be provided, not both". This message is confusing because the caller did not explicitly pass a geodataframe. It would be clearer to detect mask_arrays in the decorator and raise a dedicated ValueError indicating that area cannot be combined with mask_arrays.

        if area is not None and geodataframe is not None:
            raise ValueError("Only one of 'area' or 'geodataframe' may be provided, not both.")

        if area is not None:
            kwargs["geodataframe"] = _area_to_geodataframe(area)

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

[EddyCMWF]

@copilot apply changes based on the comments in this thread

[Copilot]

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• sites.ecmwf.int
  • Triggering command: /home/REDACTED/.local/bin/pytest pytest -q tests/test_30_spatial.py -k area pierrec/lz4/v4@v4.1.21/internal/xxh32/xxh32zero.go pierrec/lz4/v4@v4.1.21/internal/xxh32/xxh32zero_other.go /mod/golang.org/toolchain@v0.0.1-go1.25.4.linux-amd64/pkg/tool/linux_amd64/compile e/cgo ame amd64/pkg/tool/ldocs/source/how-tos/spatial/howto_mask_era5_with_geometry.ipynb /mod/golang.org/docs/source/concepts/temporal.rst --gi�� epo23g_f_xc/goladocs/source/how-tos/climatology/howto_climatology_mean_era5.ipynb /mod/golang.org/.pre-commit-config.yaml ngenv-system/pkgdocs/source/contributing.rst --quiet HEAD le ngenv-system/pkgtests/test_30_temporal_aggregate.py (dns block)
  • Triggering command: /home/REDACTED/.local/bin/pytest pytest -q tests/test_30_spatial.py::test_reduce_with_area_kwarg tests/test_30_spatial.py::test_mask_with_area_kwarg tests/test_30_spatial.py::test_area_and_positional_geodataframe_raises_reduce tests/test_30_spatial.py::test_area_and_positional_geodataframe_raises_mask inux_amd64/asm n/python x-amd64=/_/GOROOgit (dns block)
  • Triggering command: /home/REDACTED/.local/bin/pytest pytest -q tests/test_30_spatial.py -k area -delete e n/git HEAD (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)