yirgacheffe 1.9.3__py3-none-any.whl → 1.9.4__py3-none-any.whl

yirgacheffe/__init__.py

@@ -12,12 +12,13 @@ except ModuleNotFoundError:
         pyproject_data = tomllib.load(f)
     __version__ = pyproject_data["project"]["version"]
 
+from .layers import YirgacheffeLayer
 from ._core import read_raster, read_rasters, read_shape, read_shape_like, constant, read_narrow_raster
 from .constants import WGS_84_PROJECTION
 from .window import Area, MapProjection, Window
 from ._backends.enumeration import dtype as DataType
 
-from ._operators import where, minumum, maximum, clip, log, log2, log10, exp, exp2, nan_to_num, isin, \
+from ._operators import where, minimum, maximum, clip, log, log2, log10, exp, exp2, nan_to_num, isin, \
     floor, ceil # pylint: disable=W0611
 from ._operators import abs, round # pylint: disable=W0611,W0622
 

yirgacheffe/_core.py

@@ -16,7 +16,7 @@ def read_raster(
     filename: Path | str,
     band: int = 1,
     ignore_nodata: bool = False,
-) -> RasterLayer:
+) -> YirgacheffeLayer:
     """Open a raster file (e.g., GeoTIFF).
 
     Args:
@@ -38,7 +38,7 @@ def read_narrow_raster(
     filename: Path | str,
     band: int = 1,
     ignore_nodata: bool = False,
-) -> RasterLayer:
+) -> YirgacheffeLayer:
     """Open a 1 pixel wide raster file as a global raster.
 
     This exists for the special use case where an area per pixel raster would have the same value per horizontal row
@@ -58,7 +58,7 @@ def read_narrow_raster(
 def read_rasters(
     filenames : Sequence[Path | str],
     tiled: bool=False
-) -> GroupLayer:
+) -> YirgacheffeLayer:
     """Open a set of raster files (e.g., GeoTIFFs) as a single layer.
 
     Args:
@@ -86,7 +86,7 @@ def read_shape(
     where_filter: str | None = None,
     datatype: DataType | None = None,
     burn_value: int | float | str = 1,
-) -> VectorLayer:
+) -> YirgacheffeLayer:
     """Open a polygon file (e.g., GeoJSON, GPKG, or ESRI Shape File).
 
     Args:
@@ -124,7 +124,7 @@ def read_shape_like(
     where_filter: str | None = None,
     datatype: DataType | None = None,
     burn_value: int | float | str = 1,
-) -> VectorLayer:
+) -> YirgacheffeLayer:
     """Open a polygon file (e.g., GeoJSON, GPKG, or ESRI Shape File).
 
     Args:
@@ -146,7 +146,7 @@ def read_shape_like(
         burn_value,
     )
 
-def constant(value: int | float) -> ConstantLayer:
+def constant(value: int | float) -> YirgacheffeLayer:
     """Generate a layer that has the same value in all pixels regardless of scale, projection, and area.
 
     Generally this should not be necessary unless you must have the constant as the first term in an

yirgacheffe/_operators.py

@@ -10,12 +10,12 @@ import sys
 import tempfile
 import time
 import types
+from collections.abc import Callable
 from contextlib import ExitStack
 from enum import Enum
 from multiprocessing import Semaphore, Process
 from multiprocessing.managers import SharedMemoryManager
 from pathlib import Path
-from typing import Callable
 
 import deprecation
 import numpy as np
@@ -393,31 +393,34 @@ class LayerMathMixin:
 class LayerOperation(LayerMathMixin):
 
     @staticmethod
+    @deprecation.deprecated(
+        deprecated_in="1.10",
+        removed_in="2.0",
+        current_version=__version__,
+        details="Use from top level module instead."
+    )
     def where(cond, a, b):
-        return LayerOperation(
-            cond,
-            op.WHERE,
-            rhs=a,
-            other=b
-        )
+        return where(cond, a, b)
 
     @staticmethod
-    def maximum(a, b):
-        return LayerOperation(
-            a,
-            op.MAXIMUM,
-            b,
-            window_op=WindowOperation.UNION,
-        )
+    @deprecation.deprecated(
+        deprecated_in="1.10",
+        removed_in="2.0",
+        current_version=__version__,
+        details="Use from top level module instead."
+    )
+    def minimum(a, b):
+        return minimum(a, b)
 
     @staticmethod
-    def minimum(a, b):
-        return LayerOperation(
-            a,
-            op.MINIMUM,
-            rhs=b,
-            window_op=WindowOperation.UNION,
-        )
+    @deprecation.deprecated(
+        deprecated_in="1.10",
+        removed_in="2.0",
+        current_version=__version__,
+        details="Use from top level module instead."
+    )
+    def maximum(a, b):
+        return maximum(a, b)
 
     def __init__(
         self,
@@ -999,7 +1002,8 @@ class LayerOperation(LayerMathMixin):
         self,
         filename: Path | str,
         and_sum: bool = False,
-        parallelism: int | bool | None = None
+        parallelism: int | bool | None = None,
+        callback: Callable[[float], None] | None = None,
     ) -> float | None:
         """Saves a calculation to a raster file, optionally also returning the sum of pixels.
 
@@ -1009,6 +1013,8 @@ class LayerOperation(LayerMathMixin):
                 that value.
             parallelism: If passed, attempt to use multiple CPU cores up to the number provided, or if set to True,
                 yirgacheffe will pick a sensible value.
+            callback: If passed, this callback will be called periodically with a progress update for the saving,
+                with a value between 0.0 and 1.0.
 
         Returns:
             Either returns None, or the sum of the pixels in the resulting raster if `and_sum` was specified.
@@ -1026,12 +1032,12 @@ class LayerOperation(LayerMathMixin):
             from yirgacheffe.layers.rasters import RasterLayer # type: ignore # pylint: disable=C0415
             with RasterLayer.empty_raster_layer_like(self, filename=tempory_file.name) as layer:
                 if parallelism is None:
-                    result = self.save(layer, and_sum=and_sum)
+                    result = self.save(layer, and_sum=and_sum, callback=callback)
                 else:
                     if isinstance(parallelism, bool):
                         # Parallel save treats None as "work it out"
                         parallelism = None
-                    result = self.parallel_save(layer, and_sum=and_sum, parallelism=parallelism)
+                    result = self.parallel_save(layer, and_sum=and_sum, callback=callback, parallelism=parallelism)
 
             os.makedirs(target_dir, exist_ok=True)
             os.rename(src=tempory_file.name, dst=filename)
@@ -1121,10 +1127,70 @@ class ShaderStyleOperation(LayerOperation):
 
         return result
 
+def where(cond, a, b):
+    """Return elements chosen from `a` or `b` depending on `cond`.
+
+    Behaves like numpy.where(condition, x, y), returning a layer operation
+    where elements from `a` are selected where `cond` is True, and elements
+    from `b` are selected where `cond` is False.
+
+    Args:
+        cond: Layer or constant used as condition. Where True, yield `a`, otherwise yield `b`.
+        a: Layer or constant with values from which to choose where `cond` is True.
+        b: Layer or constant with values from which to choose where `cond` is False.
+
+    Returns:
+        New layer representing the conditional selection.
+    """
+    return LayerOperation(
+        cond,
+        op.WHERE,
+        rhs=a,
+        other=b
+    )
+
+def maximum(a, b):
+    """Element-wise maximum of layer elements.
+
+    Behaves like numpy.maximum(x1, x2), comparing two layers element-by-element
+    and returning a new layer with the maximum values.
+
+    Args:
+        a: First layer or constant to compare.
+        b: Second layer or constant to compare.
+
+    Returns:
+        New layer representing the element-wise maximum of the inputs.
+    """
+    return LayerOperation(
+        a,
+        op.MAXIMUM,
+        b,
+        window_op=WindowOperation.UNION,
+    )
+
+def minimum(a, b):
+    """Element-wise minimum of layer elements.
+
+    Behaves like numpy.minimum(x1, x2), comparing two layers element-by-element
+    and returning a new layer with the minimum values.
+
+    Args:
+        a: First layer or constant to compare.
+        b: Second layer or constant to compare.
+
+    Returns:
+        New layer representing the element-wise minimum of the inputs.
+    """
+    return LayerOperation(
+        a,
+        op.MINIMUM,
+        rhs=b,
+        window_op=WindowOperation.UNION,
+    )
+
+
 # We provide these module level accessors as it's often nicer to write `log(x/y)` rather than `(x/y).log()`
-where = LayerOperation.where
-minumum = LayerOperation.minimum
-maximum = LayerOperation.maximum
 clip = LayerOperation.clip
 log = LayerOperation.log
 log2 = LayerOperation.log2

yirgacheffe/operators.py

@@ -1,7 +1,7 @@
 # Eventually all this should be moved to the top level in 2.0, but for backwards compatibility in 1.x needs
 # to remain here
 
-from ._operators import where, minumum, maximum, clip, log, log2, log10, exp, exp2, nan_to_num, isin, \
+from ._operators import where, minimum, maximum, clip, log, log2, log10, exp, exp2, nan_to_num, isin, \
     floor, ceil # pylint: disable=W0611
 from ._operators import abs, round # pylint: disable=W0611,W0622
 from ._backends.enumeration import dtype as DataType # pylint: disable=W0611

{yirgacheffe-1.9.3.dist-info → yirgacheffe-1.9.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: yirgacheffe
-Version: 1.9.3
+Version: 1.9.4
 Summary: Abstraction of gdal datasets for doing basic math operations
 Author-email: Michael Dales <mwd24@cam.ac.uk>
 License-Expression: ISC
@@ -106,11 +106,42 @@ with (
     yg.read_shape('species123.geojson') as range_map,
 ):
     refined_habitat = habitat_map.isin([...species habitat codes...])
-    refined_elevation = (elevation_map >= species_min) && (elevation_map <= species_max)
+    refined_elevation = (elevation_map >= species_min) & (elevation_map <= species_max)
     aoh = refined_habitat * refined_elevation * range_polygon * area_per_pixel_map
     print(f'Area of habitat: {aoh.sum()}')
 ```
 
+## Citation
+
+If you use Yirgacheffe in your research, please cite our paper:
+
+> Michael Winston Dales, Alison Eyres, Patrick Ferris, Francesca A. Ridley, Simon Tarr, and Anil Madhavapeddy. 2025. Yirgacheffe: A Declarative Approach to Geospatial Data. In *Proceedings of the 2nd ACM SIGPLAN International Workshop on Programming for the Planet* (PROPL '25). Association for Computing Machinery, New York, NY, USA, 47–54. https://doi.org/10.1145/3759536.3763806
+
+<details>
+<summary>BibTeX</summary>
+
+```bibtex
+@inproceedings{10.1145/3759536.3763806,
+  author = {Dales, Michael Winston and Eyres, Alison and Ferris, Patrick and Ridley, Francesca A. and Tarr, Simon and Madhavapeddy, Anil},
+  title = {Yirgacheffe: A Declarative Approach to Geospatial Data},
+  year = {2025},
+  isbn = {9798400721618},
+  publisher = {Association for Computing Machinery},
+  address = {New York, NY, USA},
+  url = {https://doi.org/10.1145/3759536.3763806},
+  doi = {10.1145/3759536.3763806},
+  abstract = {We present Yirgacheffe, a declarative geospatial library that allows spatial algorithms to be implemented concisely, supports parallel execution, and avoids common errors by automatically handling data (large geospatial rasters) and resources (cores, memory, GPUs). Our primary user domain comprises ecologists, where a typical problem involves cleaning messy occurrence data, overlaying it over tiled rasters, combining layers, and deriving actionable insights from the results. We describe the successes of this approach towards driving key pipelines related to global biodiversity and describe the capability gaps that remain, hoping to motivate more research into geospatial domain-specific languages.},
+  booktitle = {Proceedings of the 2nd ACM SIGPLAN International Workshop on Programming for the Planet},
+  pages = {47–54},
+  numpages = {8},
+  keywords = {Biodiversity, Declarative, Geospatial, Python},
+  location = {Singapore, Singapore},
+  series = {PROPL '25}
+}
+```
+
+</details>
+
 ## Thanks
 
 Thanks to discussion and feedback from my colleagues, particularly Alison Eyres, Patrick Ferris, Amelia Holcomb, and Anil Madhavapeddy.

{yirgacheffe-1.9.3.dist-info → yirgacheffe-1.9.4.dist-info}/RECORD

@@ -1,8 +1,8 @@
-yirgacheffe/__init__.py,sha256=hDiVV0R4WCaRvYU_sBkL8Q6XO2PxFBM07fzNHYUGVJ0,878
-yirgacheffe/_core.py,sha256=AU6tlqovBV_l1dNZs6AlHSw59Z0U6pStUaQZvJGiLhM,5721
-yirgacheffe/_operators.py,sha256=cEjURX3GxI2kaNJwTy7JknaFsXNZTvRJj6yNLFvWTm0,41252
+yirgacheffe/__init__.py,sha256=JWQOJP_RPlBmN_N3vPGH-9FByjRQKCWUSnsh4fPNtW8,915
+yirgacheffe/_core.py,sha256=-X6wTjAKagcjWcH14IKp75Nf-kANO_Nsd8wKm5XEQzE,5750
+yirgacheffe/_operators.py,sha256=VGQ9AOOJP6cxsr_G2kxdaPaXqKi7K1csocxsudlRwVc,43440
 yirgacheffe/constants.py,sha256=bKUjOGNj19zwggV79lJgK7tiv51DH2-rgNOKswl2gvQ,293
-yirgacheffe/operators.py,sha256=nw-BpnAwTjCwFtjosa8wKd2MGUuC0PJR5jACFdLhqCg,412
+yirgacheffe/operators.py,sha256=Y1KkNt79N1elR4ZplQaQngx29wdf2QFF_5la4PI3EhI,412
 yirgacheffe/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 yirgacheffe/rounding.py,sha256=Jzd9qlLnLpigT95GbQTByvYOo639Nfq4LBEVyvhYdoc,2289
 yirgacheffe/window.py,sha256=QuyBLOwKFI0XkEQ4Bd2hdELPbJSfHL7mt5KSi7CIHcE,9505
@@ -19,9 +19,9 @@ yirgacheffe/layers/h3layer.py,sha256=Rq1bFo7CApIh5NdBcV7hSj3hm-DszY79nhYsTRAvJ_g
 yirgacheffe/layers/rasters.py,sha256=zBE9uXm6LvAQF2_XdQzcOgJQOQWGmuPflY5JNDrUf3k,13527
 yirgacheffe/layers/rescaled.py,sha256=gEFbXeYxX1nVn7eQYmbGww90_yc5ENmgQrD_WxXxpQE,3352
 yirgacheffe/layers/vectors.py,sha256=A27kuTr0C9BZhHG0-cplNEa7aSNcse37Pm9xTjEzv-c,19990
-yirgacheffe-1.9.3.dist-info/licenses/LICENSE,sha256=dNSHwUCJr6axStTKDEdnJtfmDdFqlE3h1NPCveqPfnY,757
-yirgacheffe-1.9.3.dist-info/METADATA,sha256=g6QH8LpSDGzWwQZ33Swkb0lt61jbI95kTFM-VklAQZ8,5429
-yirgacheffe-1.9.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-yirgacheffe-1.9.3.dist-info/entry_points.txt,sha256=j4KgHXbVGbGyfTySc1ypBdERpfihO4WNjppvCdE9HjE,52
-yirgacheffe-1.9.3.dist-info/top_level.txt,sha256=9DBFlKO2Ld3hG6TuE3qOTd3Tt8ugTiXil4AN4Wr9_y0,12
-yirgacheffe-1.9.3.dist-info/RECORD,,
+yirgacheffe-1.9.4.dist-info/licenses/LICENSE,sha256=dNSHwUCJr6axStTKDEdnJtfmDdFqlE3h1NPCveqPfnY,757
+yirgacheffe-1.9.4.dist-info/METADATA,sha256=cUAABIwPG9_RTO0ylH25O_7usbtQneZwTUCsfk_SLIs,7407
+yirgacheffe-1.9.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+yirgacheffe-1.9.4.dist-info/entry_points.txt,sha256=j4KgHXbVGbGyfTySc1ypBdERpfihO4WNjppvCdE9HjE,52
+yirgacheffe-1.9.4.dist-info/top_level.txt,sha256=9DBFlKO2Ld3hG6TuE3qOTd3Tt8ugTiXil4AN4Wr9_y0,12
+yirgacheffe-1.9.4.dist-info/RECORD,,