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

yirgacheffe/__init__.py

@@ -12,12 +12,13 @@ except ModuleNotFoundError:
         pyproject_data = tomllib.load(f)
     __version__ = pyproject_data["project"]["version"]
 
-from ._core import read_raster, read_rasters, read_shape, read_shape_like, constant, read_narrow_raster
+from .layers import YirgacheffeLayer
+from ._core import read_raster, read_rasters, read_shape, read_shape_like, constant, read_narrow_raster, from_array
 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/_backends/enumeration.py

@@ -1,5 +1,8 @@
+from __future__ import annotations
+
 from enum import Enum
 
+import numpy as np
 from osgeo import gdal
 
 class operators(Enum):
@@ -77,5 +80,31 @@ class dtype(Enum):
         return self.value
 
     @classmethod
-    def of_gdal(cls, val):
+    def of_gdal(cls, val: int) -> dtype:
         return cls(val)
+
+    @classmethod
+    def of_array(cls, val: np.ndarray) -> dtype:
+        match val.dtype:
+            case np.float32:
+                return dtype.Float32
+            case np.float64:
+                return dtype.Float64
+            case np.int8:
+                return dtype.Int8
+            case np.int16:
+                return dtype.Int16
+            case np.int32:
+                return dtype.Int32
+            case np.int64:
+                return dtype.Int64
+            case np.uint8:
+                return dtype.UInt8
+            case np.uint16:
+                return dtype.UInt16
+            case np.uint32:
+                return dtype.UInt32
+            case np.uint64:
+                return dtype.UInt64
+            case _:
+                raise ValueError

yirgacheffe/_core.py

@@ -3,20 +3,22 @@ from __future__ import annotations
 from pathlib import Path
 from typing import Sequence
 
+import numpy as np
+
 from .layers.area import UniformAreaLayer
 from .layers.base import YirgacheffeLayer
 from .layers.constant import ConstantLayer
 from .layers.group import GroupLayer, TiledGroupLayer
 from .layers.rasters import RasterLayer
 from .layers.vectors import VectorLayer
-from .window import MapProjection
+from .window import Area, MapProjection
 from ._backends.enumeration import dtype as DataType
 
 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 +40,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 +60,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 +88,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 +126,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 +148,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
@@ -161,3 +163,50 @@ def constant(value: int | float) -> ConstantLayer:
         A constant layer of the provided value.
     """
     return ConstantLayer(value)
+
+def from_array(
+    values: np.ndarray,
+    origin: tuple[float, float],
+    projection: MapProjection | tuple[str, tuple[float, float]],
+) -> YirgacheffeLayer:
+    """Creates an in-memory layer from a numerical array.
+
+    Args:
+        values: a 2D array of data values, with Y on the first dimension, X on
+            the second dimension.
+        origin: the position of the top left pixel in the geospatial space
+        projection: the map projection and pixel scale to use.
+
+    Returns:
+        A geospatial layer that uses the provided data for its values.
+    """
+
+    if projection is None:
+        raise ValueError("Projection must not be none")
+
+    if not isinstance(projection, MapProjection):
+        projection_name, scale_tuple = projection
+        projection = MapProjection(projection_name, scale_tuple[0], scale_tuple[1])
+
+    dims = values.shape
+
+    area = Area(
+        left=origin[0],
+        top=origin[1],
+        right=origin[0] + (projection.xstep * dims[1]),
+        bottom=origin[1] + (projection.ystep * dims[0])
+    )
+
+    layer = RasterLayer.empty_raster_layer(
+        area,
+        scale=projection.scale,
+        datatype=DataType.of_array(values),
+        filename=None,
+        projection=projection.name,
+    )
+    assert layer._dataset
+    assert layer._dataset.RasterXSize == dims[1]
+    assert layer._dataset.RasterYSize == dims[0]
+    layer._dataset.GetRasterBand(1).WriteArray(values, 0, 0)
+
+    return layer

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/layers/group.py

@@ -81,7 +81,7 @@ class GroupLayer(YirgacheffeLayer):
 
     @property
     def datatype(self) -> DataType:
-        return DataType.of_gdal(self.layers[0].datatype)
+        return self.layers[0].datatype
 
     def set_window_for_intersection(self, new_area: Area) -> None:
         super().set_window_for_intersection(new_area)

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/window.py

@@ -22,6 +22,15 @@ class MapProjection:
         name: The map projection used in WKT format.
         xstep: The number of units horizontal distance a step of one pixel makes in the map projection.
         ystep: The number of units vertical distance a step of one pixel makes in the map projection.
+
+    Examples:
+        Create a map projection using an EPSG code:
+
+        >>> proj_wgs84 = MapProjection("epsg:4326", 0.001, -0.001)
+
+        Create a projection using an ESRI code:
+
+        >>> proj_esri = MapProjection("esri:54030", 1000, -1000)
     """
 
     def __init__(self, projection_string: str, xstep: float, ystep: float) -> None:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: yirgacheffe
-Version: 1.9.3
+Version: 1.9.5
 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.5.dist-info}/RECORD

@@ -1,27 +1,27 @@
-yirgacheffe/__init__.py,sha256=hDiVV0R4WCaRvYU_sBkL8Q6XO2PxFBM07fzNHYUGVJ0,878
-yirgacheffe/_core.py,sha256=AU6tlqovBV_l1dNZs6AlHSw59Z0U6pStUaQZvJGiLhM,5721
-yirgacheffe/_operators.py,sha256=cEjURX3GxI2kaNJwTy7JknaFsXNZTvRJj6yNLFvWTm0,41252
+yirgacheffe/__init__.py,sha256=Ps6W8A1TRriVNxZEF3jW1_KOLEtji4ffyoGRmQXne8g,927
+yirgacheffe/_core.py,sha256=Tr6RAiRZOO3vbtiTjLoNRjjd1DkXYZOgpDqrjs7jCBw,7231
+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
+yirgacheffe/window.py,sha256=kAAsE3t49DbffrW78DLZuGwgT-MCpM3WBJQ-5MO5ciM,9755
 yirgacheffe/_backends/__init__.py,sha256=jN-2iRrHStnPI6cNL7XhwhsROtI0EaGfIrbF5c-ECV0,334
-yirgacheffe/_backends/enumeration.py,sha256=9bcCXz9Ssrh8Oh1iazodkx6Gm2kQBi9HQ9z9zehS4AE,1806
+yirgacheffe/_backends/enumeration.py,sha256=Clb-oRha65po_dED_lECXjnih-n77CtUg18-34xX6nA,2652
 yirgacheffe/_backends/mlx.py,sha256=U1gl1lK1mZXLEET6ylF1TNs6WJ0PBEvfSk7ppn28n8w,6203
 yirgacheffe/_backends/numpy.py,sha256=Gxx49JJH79GFEkKIpV6IyjCUcdtN5-qLlzRfylzKhS4,4142
 yirgacheffe/layers/__init__.py,sha256=mYKjw5YTcMNv_hMy7a6K4yRzIuNUbR8WuBTw4WIAmSk,435
 yirgacheffe/layers/area.py,sha256=wJcMHbLJBaXS4BeFbu5rYeKfgu3gvaE9hwQ5j6aw-y4,3976
 yirgacheffe/layers/base.py,sha256=7b4WXuvnmCv8mR0iyCIuSEolnV8D3f2vtCaYlcJCIa8,13201
 yirgacheffe/layers/constant.py,sha256=gtkQ98Z01CYYDgFElswtRZY4ZG3UnS5NIAoIVue5ufk,1481
-yirgacheffe/layers/group.py,sha256=yaqf-ra_Vh59yrWcz7-OvJ1fBnTcBXZd18AfRDN5Ymo,16157
+yirgacheffe/layers/group.py,sha256=jFJ60YcbkLNeD-2w3QOLwbcYEWdgicrXMClIo2vz97Q,16139
 yirgacheffe/layers/h3layer.py,sha256=Rq1bFo7CApIh5NdBcV7hSj3hm-DszY79nhYsTRAvJ_g,9916
 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.5.dist-info/licenses/LICENSE,sha256=dNSHwUCJr6axStTKDEdnJtfmDdFqlE3h1NPCveqPfnY,757
+yirgacheffe-1.9.5.dist-info/METADATA,sha256=TvX6Nwvdp_u80s9PXHCvSoxndvp4mjOBE1wRcn-neL0,7407
+yirgacheffe-1.9.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+yirgacheffe-1.9.5.dist-info/entry_points.txt,sha256=j4KgHXbVGbGyfTySc1ypBdERpfihO4WNjppvCdE9HjE,52
+yirgacheffe-1.9.5.dist-info/top_level.txt,sha256=9DBFlKO2Ld3hG6TuE3qOTd3Tt8ugTiXil4AN4Wr9_y0,12
+yirgacheffe-1.9.5.dist-info/RECORD,,