From 4d39b30258aa1a87546eebd8670a4203821f3e4b Mon Sep 17 00:00:00 2001 From: Brewster Malevich Date: Mon, 6 Jul 2026 18:05:23 -0700 Subject: [PATCH 1/3] Fill out extract_regions docstr --- src/isku/extract.py | 26 ++++++++++++++++++++++---- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/src/isku/extract.py b/src/isku/extract.py index e61b457..f3d37a9 100644 --- a/src/isku/extract.py +++ b/src/isku/extract.py @@ -135,12 +135,30 @@ def extract_regions( ds: xr.Dataset, *, template: ExtractionTemplate, regions: RegionExtractor ) -> xr.Dataset: """ - Use transformations in 'template' to extract 'regions' from gridded dataset, 'ds', returning a regionalized dataset - - This function specifically does not just regionalize through zonal aggregation. It uses 'template' to apply pre/post regionalization transformations to create new datasets and variables. + Regionalize a gridded dataset with a template of pre- and post-extraction transformations + + Parameters + ---------- + ds : + A gridded dataset with variables to regionalize and transform. + template : + A template describing pre- and post-regionalization trasformations to create the output regionalized data. + regions : + Regions to extract from the gridded dataset. + + Returns + ------- + out : + A regionalized dataset. + + Notes + ----- + This function is especially concerned with applying a transformation step before regions are extracted, and applying a transformation after extraction. To extract regions _without_ the surrounding transformations, use the [extract_regions][isku.RegionExtractor.extract_regions] method on whatever was passed for the `regions` argument. See Also -------- - build_extraction_template: Quickly build extraction workflow from functions for regionalization. + [build_extraction_template][isku.build_extraction_template]: Quickly build extraction templates from functions. + + [GridWeightingRegions][isku.GridWeightingRegions]: An example of a [RegionExtractor][isku.RegionExtractor] that can be used for the `regions` argument. """ return template.post_extract(regions.extract_regions(template.pre_extract(ds))) From 9479d62618ad5da891bfcd7185b6f26be6dcf575 Mon Sep 17 00:00:00 2001 From: Brewster Malevich Date: Mon, 6 Jul 2026 18:18:54 -0700 Subject: [PATCH 2/3] Remove function args from TOC in API Reference docs --- zensical.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/zensical.toml b/zensical.toml index b17bf9b..b1994ba 100644 --- a/zensical.toml +++ b/zensical.toml @@ -378,7 +378,7 @@ docstring_style = "numpy" separate_signature = true # preload_modules = ["xarray"] # Xarray does not work with intersphinx inventories...? (https://github.com/pydata/xarray/issues/4279) members_order = "source" -parameter_headings = true +parameter_headings = false type_parameter_headings = true docstring_section_style = "list" show_object_full_path = false From c11d60cddb5630eb0d9a80c4e264cdfa79a5a302 Mon Sep 17 00:00:00 2001 From: Brewster Malevich Date: Wed, 8 Jul 2026 16:51:05 -0700 Subject: [PATCH 3/3] Add changelog entry --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9a884fc..be09f34 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Minor improvements to README, CONTRIBUTING docs, developer experience. ([@brews](https://github.com/brews), [PR#42](https://github.com/ClimateImpactLab/isku/pull/42)) - Mention "segment weights" in `GridWeightingRegions` API docs. ([@brews](https://github.com/brews), [PR#60](https://github.com/ClimateImpactLab/isku/pull/60)) +- Improve documentation for `isku.extract_regions`. ([@brews](https://github.com/brews), [PR#73](https://github.com/ClimateImpactLab/isku/pull/73)) ## [0.3.0] - 2026-05-15