isku 0.1.0__tar.gz

isku-0.1.0/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.3
+Name: isku
+Version: 0.1.0
+Summary: Minimalist Python + xarray-based climate impact/damage projection framework for researchers with little time.
+Author: Brewster Malevich
+Author-email: Brewster Malevich <bmalevich@rhg.com>
+Requires-Dist: xarray>=2026.4.0
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# isku
+
+Minimalist Python + xarray-based climate impact/damage projection framework for researchers with little time.
+
+> [!CAUTION]
+> This is a prototype. It is likely to change in breaking ways. It might delete all your data. Don't use it in production.
+
+## Features
+
+* Define and apply three-step models to project climate effects, impacts, and damages.
+
+* Extract regionalized variables from regularly gridded data, such as downscaled general circulation model output.
+
+* Minimalist.
+
+* Loosely coupled components and protocols for quick scripts with functions or gnarly OOP-heavy applications.
+
+* Designed around `xarray.Dataset` to work with larger-than-memory datasets and distributed computing (dask!), GPUs, TPUs, streaming datasets.
+
+* Great for weird ad hoc projects and researchers that love rechunking big data!
+
+## Example
+
+### Projection
+
+Projecting data with a model in `isku` is similar to the preprocess/predict/postprocess workflow you might already be familar with.
+
+In `isku`, we could do a linear model with pre/post-processing like:
+
+```python
+import isku
+
+import numpy as np
+import xarray as xr
+
+# Some toy input data to work with.
+input_data = xr.Dataset(
+    {
+        "coef": (["region"], [0, 0, 0]),
+        "tas": (["region"], [1, 2, 3]),
+    }
+)
+
+# Define a basic workflow for the projection model, pre/post-processing steps.
+def _preprocess(ds):
+    my_coef = ds["coef"] + 1
+    my_tas = ds["tas"]
+    return xr.Dataset({"coef": my_coef, "tas": my_tas})
+
+
+def _linear_impact_model(ds):
+    y = ds["coef"] * 2 + ds["tas"]
+    return xr.Dataset({"impact": y})
+
+
+def _postprocess(ds):
+    return ds[["impact"]] + 10
+
+
+test_impact_model = isku.build_projection_workflow(
+    pre=_preprocess,
+    project=_linear_impact_model,
+    post=_postprocess,
+)
+
+# Put it together and run the projection.
+projected = isku.project(input_data, model=test_impact_model)
+```
+
+This example uses pure functions to define workflow steps. This can be useful for quick analysis but `isku` also accepts
+custom objects adhering to the select protocols. The intent is that components can be quickly used, ignored, extended or
+replaced as needed by a project.
+
+### Extracting regions
+
+The relationship between data transformations and region extraction can be complex in impact and damage research.
+
+Say you have temperature data on a regular latitude-longitude grid. You need to extract regions from this grid, e.g.
+political boundaries, but you need to weight each temperature grid point by the proportion of the region's population
+exposed to temperature within each region. To make matters more complex you likely need to be specific about additional processing and transformation
+before and after regionalization. This is a niche case but a common headache.
+
+We can handle this type of transformation in `isku` like:
+
+```python
+import isku
+
+import numpy as np
+import xarray as xr
+
+
+# Define some toy data to transform and regionalize.
+gridded_data = xr.DataArray(
+    np.arange(25).reshape([5, 5]),
+    dims=("lon", "lat"),
+    coords={
+        "lon": np.arange(5),
+        "lat": np.arange(5),
+    },
+    name="variable1",
+).to_dataset()
+
+# Refine regions and how they weight each grid point in the gridded data.
+# This is usually read from file, but we're making up a quick example dataset.
+my_regions = isku.GridWeightingRegions(
+    xr.Dataset(
+        {
+            "region": (["idx"], ["a", "a", "a", "b"]),
+            "weight": (["idx"], [0.3, 0.3, 0.3, 1.0]),
+            "lon": (["idx"], [2, 3, 4, 1]),
+            "lat": (["idx"], [0, 0, 0, 2]),
+        },
+    )
+)
+
+# Define workflow with pre/post regionalization transformations.
+def _add_one(ds):
+    return ds[["variable1"]] + 1
+
+
+def _add_ten(ds):
+    return ds[["variable1"]] + 10
+
+
+my_extraction_workflow = isku.build_extraction_workflow(
+    pre=_add_one,  # Before regionalization.
+    post=_add_ten,  # After regionalization.
+)
+
+
+# Put it all together to extract regions from gridded data.
+transformed = isku.extract_regions(
+    gridded_data,
+    workflow=my_extraction_workflow,
+    regions=my_regions,
+)
+```
+
+
+## Installation
+
+Using `pip` you can install this package with
+
+```
+pip install isku
+```
+
+for a `uv` project this is
+
+```
+uv add isku
+```
+
+Install the unreleased and unstable bleeding-edge version of the package with:
+
+```shell
+pip install git+https://github.com/brews/isku
+```
+
+using `pip` or with a project in `uv`, do
+
+```shell
+uv add git+https://github.com/brews/isku
+```
+
+## Is this any good?
+
+Yes.
+
+## Support
+
+`isku` is open-source software made available under the terms of either the MIT License or the Apache License 2.0, at your option.
+
+See CONTRIBUTING.md if you would like to contribute.
+
+Changes for each release are summarized in CHANGELOG.md.

isku-0.1.0/README.md

@@ -0,0 +1,176 @@
+# isku
+
+Minimalist Python + xarray-based climate impact/damage projection framework for researchers with little time.
+
+> [!CAUTION]
+> This is a prototype. It is likely to change in breaking ways. It might delete all your data. Don't use it in production.
+
+## Features
+
+* Define and apply three-step models to project climate effects, impacts, and damages.
+
+* Extract regionalized variables from regularly gridded data, such as downscaled general circulation model output.
+
+* Minimalist.
+
+* Loosely coupled components and protocols for quick scripts with functions or gnarly OOP-heavy applications.
+
+* Designed around `xarray.Dataset` to work with larger-than-memory datasets and distributed computing (dask!), GPUs, TPUs, streaming datasets.
+
+* Great for weird ad hoc projects and researchers that love rechunking big data!
+
+## Example
+
+### Projection
+
+Projecting data with a model in `isku` is similar to the preprocess/predict/postprocess workflow you might already be familar with.
+
+In `isku`, we could do a linear model with pre/post-processing like:
+
+```python
+import isku
+
+import numpy as np
+import xarray as xr
+
+# Some toy input data to work with.
+input_data = xr.Dataset(
+    {
+        "coef": (["region"], [0, 0, 0]),
+        "tas": (["region"], [1, 2, 3]),
+    }
+)
+
+# Define a basic workflow for the projection model, pre/post-processing steps.
+def _preprocess(ds):
+    my_coef = ds["coef"] + 1
+    my_tas = ds["tas"]
+    return xr.Dataset({"coef": my_coef, "tas": my_tas})
+
+
+def _linear_impact_model(ds):
+    y = ds["coef"] * 2 + ds["tas"]
+    return xr.Dataset({"impact": y})
+
+
+def _postprocess(ds):
+    return ds[["impact"]] + 10
+
+
+test_impact_model = isku.build_projection_workflow(
+    pre=_preprocess,
+    project=_linear_impact_model,
+    post=_postprocess,
+)
+
+# Put it together and run the projection.
+projected = isku.project(input_data, model=test_impact_model)
+```
+
+This example uses pure functions to define workflow steps. This can be useful for quick analysis but `isku` also accepts
+custom objects adhering to the select protocols. The intent is that components can be quickly used, ignored, extended or
+replaced as needed by a project.
+
+### Extracting regions
+
+The relationship between data transformations and region extraction can be complex in impact and damage research.
+
+Say you have temperature data on a regular latitude-longitude grid. You need to extract regions from this grid, e.g.
+political boundaries, but you need to weight each temperature grid point by the proportion of the region's population
+exposed to temperature within each region. To make matters more complex you likely need to be specific about additional processing and transformation
+before and after regionalization. This is a niche case but a common headache.
+
+We can handle this type of transformation in `isku` like:
+
+```python
+import isku
+
+import numpy as np
+import xarray as xr
+
+
+# Define some toy data to transform and regionalize.
+gridded_data = xr.DataArray(
+    np.arange(25).reshape([5, 5]),
+    dims=("lon", "lat"),
+    coords={
+        "lon": np.arange(5),
+        "lat": np.arange(5),
+    },
+    name="variable1",
+).to_dataset()
+
+# Refine regions and how they weight each grid point in the gridded data.
+# This is usually read from file, but we're making up a quick example dataset.
+my_regions = isku.GridWeightingRegions(
+    xr.Dataset(
+        {
+            "region": (["idx"], ["a", "a", "a", "b"]),
+            "weight": (["idx"], [0.3, 0.3, 0.3, 1.0]),
+            "lon": (["idx"], [2, 3, 4, 1]),
+            "lat": (["idx"], [0, 0, 0, 2]),
+        },
+    )
+)
+
+# Define workflow with pre/post regionalization transformations.
+def _add_one(ds):
+    return ds[["variable1"]] + 1
+
+
+def _add_ten(ds):
+    return ds[["variable1"]] + 10
+
+
+my_extraction_workflow = isku.build_extraction_workflow(
+    pre=_add_one,  # Before regionalization.
+    post=_add_ten,  # After regionalization.
+)
+
+
+# Put it all together to extract regions from gridded data.
+transformed = isku.extract_regions(
+    gridded_data,
+    workflow=my_extraction_workflow,
+    regions=my_regions,
+)
+```
+
+
+## Installation
+
+Using `pip` you can install this package with
+
+```
+pip install isku
+```
+
+for a `uv` project this is
+
+```
+uv add isku
+```
+
+Install the unreleased and unstable bleeding-edge version of the package with:
+
+```shell
+pip install git+https://github.com/brews/isku
+```
+
+using `pip` or with a project in `uv`, do
+
+```shell
+uv add git+https://github.com/brews/isku
+```
+
+## Is this any good?
+
+Yes.
+
+## Support
+
+`isku` is open-source software made available under the terms of either the MIT License or the Apache License 2.0, at your option.
+
+See CONTRIBUTING.md if you would like to contribute.
+
+Changes for each release are summarized in CHANGELOG.md.

isku-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "isku"
+version = "0.1.0"
+description = "Minimalist Python + xarray-based climate impact/damage projection framework for researchers with little time."
+readme = "README.md"
+authors = [
+    { name = "Brewster Malevich", email = "bmalevich@rhg.com" }
+]
+requires-python = ">=3.14"
+dependencies = [
+    "xarray>=2026.4.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.11,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "numpy>=2.4.4",
+    "pytest>=9.0.3",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.15.12",
+    "ty>=0.0.33",
+    "zensical>=0.0.40",
+]

isku-0.1.0/src/isku/__init__.py

@@ -0,0 +1,222 @@
+from dataclasses import dataclass
+from typing import Protocol, Callable
+
+import xarray as xr
+
+
+__all__ = [
+    "build_extraction_workflow",
+    "extract_regions",
+    "build_projection_workflow",
+    "project",
+    "GridWeightingRegions",
+    "ExtractionWorkflow",
+    "RegionExtractor",
+    "ProjectionWorkflow",
+]
+
+
+class ExtractionWorkflow(Protocol):
+    """
+    Template for pre and post region extraction transformation
+
+    See Also
+    --------
+    build_extraction_workflow: Quickly build extraction workflow from functions for regionalization with pre/post transformations.
+    extract_regions: Apply a workflow to extract a new regionalized dataset from gridded data.
+    RegionExtractor: Protocol for regionalizing, or extracting regions from a dataset.
+    """
+
+    def pre_extract(self, ds: xr.Dataset) -> xr.Dataset:
+        """
+        Transform dataset before region extraction
+        """
+        ...
+
+    def post_extract(self, ds: xr.Dataset) -> xr.Dataset:
+        """
+        Transform dataset after region extraction
+        """
+        ...
+
+
+class RegionExtractor(Protocol):
+    """
+    Protocol for extracting regions from gridded data
+
+    See Also
+    --------
+    extract_regions: Apply a workflow to extract a new regionalized dataset from gridded data with pre/post transformations.
+    ExtractionWorkflow: Technical protocol for a workflow with pre/post regionalization transformations.
+    """
+
+    def extract_regions(self, ds: xr.Dataset) -> xr.Dataset:
+        """
+        Extract and aggregate gridded dataset points into regionalized dataset
+        """
+        ...
+
+
+# This dataclass is a quick and simple way to get a concrete instance of the protocol.
+@dataclass(frozen=True)
+class _SimpleExtractionWorkflow(ExtractionWorkflow):
+    pre_extract: Callable[[xr.Dataset], xr.Dataset]
+    post_extract: Callable[[xr.Dataset], xr.Dataset]
+
+
+def build_extraction_workflow(
+    *, pre: Callable[[xr.Dataset], xr.Dataset], post: Callable[[xr.Dataset], xr.Dataset]
+) -> ExtractionWorkflow:
+    """
+    Build a workflow of tranformation steps applied to input gridded data, pre/post regionalization, to create a derived variable as output
+
+    This function is a quick and simple way to build an ExtractionWorkflow from two simple functions.
+
+    These steps should be general. They may contain logic for sanity checks
+    on inputs and outputs, calculating derived variables and climate indices,
+    adding or checking metadata or units. Avoid including logic for cleaning,
+    or harmonizing input data, especially if it is specific to a single
+    project's usecase. Generally avoid using a single strategy to output
+    multiple unrelated variables.
+
+    See Also
+    --------
+    extract_regions: Apply a workflow to extract a new regionalized dataset from gridded data.
+    build_extraction_workflow: Quickly build extraction workflow from functions for regionalization.
+    ExtractionWorkflow: The underlaying protocol for a workflow that extracts a regionalized dataset.
+    """
+    return _SimpleExtractionWorkflow(pre_extract=pre, post_extract=post)
+
+
+# Use class for segment weights because we're making assumptions/enforcements about the weight data's content and interactions...
+class GridWeightingRegions(RegionExtractor):
+    """
+    Regions that can be extracted from regularly-gridded data after weighting grid points
+
+    'weights' dataset must have "lat", "lon", "weight", "region".
+
+    Raises
+    ------
+    ValueError
+        If 'weights' is missing "lat", "lon", "weight" or "region" variables.
+
+    See Also
+    --------
+    extract_regions: Use SegmentWeights in a workflow to extract new regionalized dataset.
+    build_extraction_workflow: Quickly build extraction workflow from functions for regionalization.
+    RegionExtractor: Protocol for regionalizing, or extracting regions from a dataset.
+    """
+
+    def __init__(self, weights: xr.Dataset):
+        target_variables = ("lat", "lon", "weight", "region")
+        missing_variables = [v for v in target_variables if v not in weights.variables]
+        if missing_variables:
+            raise ValueError(
+                f"input weights is missing required {missing_variables} variable(s)"
+            )
+        self._data = weights
+
+    def extract_regions(self, ds: xr.Dataset) -> xr.Dataset:
+        """
+        Regionalize input gridded data after multiplying 'ds' by weights and summing the product within each region.
+
+        'ds' must have "lat", "lon" coordinates exactly matching "lat", "lon" in weights.
+        """
+        # TODO: See how this errors in different common scenarios. What happens on the
+        #  unhappy path?
+        region_sel = ds.sel(lat=self._data["lat"], lon=self._data["lon"])
+        out = (region_sel * self._data["weight"]).groupby(self._data["region"]).sum()
+        # TODO: Maybe drop lat/lon and set 'region' as dim/coord? I feel like we can do
+        #  this because we're asking weights to strictly match input's lat/lon. Maybe
+        #  make this a req of segment weights we're reading in?
+        return out
+
+
+def extract_regions(
+    ds: xr.Dataset, *, workflow: ExtractionWorkflow, regions: RegionExtractor
+) -> xr.Dataset:
+    """
+    Use transformations in 'workflow' to extract 'regions' from gridded dataset, 'ds', returning a regionalized dataset
+
+    This function specifically does not just regionalize through zonal aggregation. It uses 'workflow' to apply pre/post regionalization transformations to create new datasets and variables.
+
+    See Also
+    --------
+    build_extraction_workflow: Quickly build extraction workflow from functions for regionalization.
+    """
+    return workflow.post_extract(regions.extract_regions(workflow.pre_extract(ds)))
+
+
+class ProjectionWorkflow(Protocol):
+    """
+    Template for projecting a model with pre and post processing.
+
+    See Also
+    --------
+    build_projection_workflow: Build a projection workflow from simple functions.
+    """
+
+    def pre_project(self, d: xr.Dataset) -> xr.Dataset:
+        """
+        Pre-process a dataset before projection
+        """
+        ...
+
+    def project(self, d: xr.Dataset) -> xr.Dataset:
+        """
+        Create a projection from a dataset
+        """
+        ...
+
+    def post_project(self, d: xr.Dataset) -> xr.Dataset:
+        """
+        Process a projected dataset
+        """
+        ...
+
+
+# This dataclass is a quick and simple way to get a concrete instance of the protocol.
+@dataclass(frozen=True)
+class _SimpleProjectionWorkflow(ProjectionWorkflow):
+    pre_project: Callable[[xr.Dataset], xr.Dataset]
+    project: Callable[[xr.Dataset], xr.Dataset]
+    post_project: Callable[[xr.Dataset], xr.Dataset]
+
+
+def build_projection_workflow(
+    *,
+    pre: Callable[[xr.Dataset], xr.Dataset],
+    project: Callable[[xr.Dataset], xr.Dataset],
+    post: Callable[[xr.Dataset], xr.Dataset],
+) -> ProjectionWorkflow:
+    """
+    Use simple functions to quickly build a model to project effects, impacts and/or damages.
+
+    This function is a quick and simple way to build an ProjectionWorkflow from three simple functions.
+
+    See Also
+    --------
+    project: Apply a projection workflow to a dataset.
+    ProjectionWorkflow: Technical ProjectionWorkflow protocol.
+    """
+    return _SimpleProjectionWorkflow(
+        pre_project=pre,
+        project=project,
+        post_project=post,
+    )
+
+
+def project(d: xr.Dataset, *, model: ProjectionWorkflow) -> xr.Dataset:
+    """
+    Project a dataset of predictors, 'd', with 'model' to return a projected dataset
+
+    See Also
+    --------
+    build_projection_workflow: Build a projection workflow from simple functions.
+    ProjectionWorkflow: Technical ProjectionWorkflow protocol.
+    """
+    preprocessed = model.pre_project(d)
+    projected = model.project(preprocessed)
+    postprocessed = model.post_project(projected)
+
+    return postprocessed