yirgacheffe 1.9.3__tar.gz → 1.9.5__tar.gz

{yirgacheffe-1.9.3/yirgacheffe.egg-info → yirgacheffe-1.9.5}/PKG-INFO

@@ -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 → yirgacheffe-1.9.5}/README.md

@@ -59,11 +59,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 → yirgacheffe-1.9.5}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "yirgacheffe"
-version = "1.9.3"
+version = "1.9.5"
 description = "Abstraction of gdal datasets for doing basic math operations"
 readme = "README.md"
 authors = [{ name = "Michael Dales", email = "mwd24@cam.ac.uk" }]

{yirgacheffe-1.9.3 → yirgacheffe-1.9.5}/tests/test_datatypes.py

@@ -64,3 +64,49 @@ def test_float_to_int() -> None:
     expected = backend.promote(np.array([[1, 2, 3, 4], [5, 6, 7, 8]]))
     actual = result.read_array(0, 0, 4, 2)
     assert (expected == actual).all()
+
+@pytest.mark.parametrize("array,expected_type", [
+    (
+        np.ones((2, 2)).astype(np.int8),
+        DataType.Int8,
+    ),
+    (
+        np.ones((2, 2)).astype(np.int16),
+        DataType.Int16,
+    ),
+    (
+        np.ones((2, 2)).astype(np.int32),
+        DataType.Int32,
+    ),
+    (
+        np.ones((2, 2)).astype(np.int64),
+        DataType.Int64,
+    ),
+    (
+        np.ones((2, 2)).astype(np.uint8),
+        DataType.UInt8,
+    ),
+    (
+        np.ones((2, 2)).astype(np.uint16),
+        DataType.UInt16,
+    ),
+    (
+        np.ones((2, 2)).astype(np.uint32),
+        DataType.UInt32,
+    ),
+    (
+        np.ones((2, 2)).astype(np.uint64),
+        DataType.UInt64,
+    ),
+    (
+        np.ones((2, 2)).astype(np.float32),
+        DataType.Float32,
+    ),
+    (
+        np.ones((2, 2)).astype(np.float64),
+        DataType.Float64,
+    ),
+])
+def test_of_Array(array: np.ndarray, expected_type: DataType) -> None:
+    ytype = DataType.of_array(array)
+    assert ytype == expected_type

{yirgacheffe-1.9.3 → yirgacheffe-1.9.5}/tests/test_multiband.py

@@ -4,7 +4,7 @@ import tempfile
 import numpy as np
 from osgeo import gdal
 
-from tests.helpers import gdal_dataset_with_data
+import yirgacheffe as yg
 from yirgacheffe.layers import RasterLayer
 from yirgacheffe.window import Area, PixelScale
 
@@ -23,9 +23,10 @@ def test_simple_two_band_image() -> None:
         )
 
         # Create a set of rasters in turn to fill each band
+        projection = yg.MapProjection("epsg:4326", 1.0, -1.0)
         for i in range(bands):
             data1 = np.full((2, 2), i+1)
-            layer1 = RasterLayer(gdal_dataset_with_data((-1.0, 1.0), 1.0, data1))
+            layer1 = yg.from_array(data1, (-1.0, 1.0), projection)
             layer1.save(target, band=i+1)
 
         # force things to disk
@@ -33,7 +34,7 @@ def test_simple_two_band_image() -> None:
 
         #check they do what we expect
         for i in range(bands):
-            o = RasterLayer.layer_from_file(target_path, band=i+1)
+            o = yg.read_raster(target_path, band=i+1)
             assert o.sum() == (4 * (i + 1))
 
 def test_stack_tifs_with_area_match() -> None:
@@ -43,9 +44,10 @@ def test_stack_tifs_with_area_match() -> None:
         # slight alignment offset when we create them)
         bands = 4
         source_layers = []
+        projection = yg.MapProjection("epsg:4326", 1.0, -1.0)
         for i in range(bands):
             data1 = np.full((100, 100), i+1)
-            layer1 = RasterLayer(gdal_dataset_with_data((-100+i, 100+i), 1, data1))
+            layer1 = yg.from_array(data1, (-100+i, 100+i), projection)
             source_layers.append(layer1)
 
         intersection = RasterLayer.find_intersection(source_layers)
@@ -66,5 +68,5 @@ def test_stack_tifs_with_area_match() -> None:
 
         #check they do what we expect
         for i in range(bands):
-            o = RasterLayer.layer_from_file(target_path, band=i+1)
+            o = yg.read_raster(target_path, band=i+1)
             assert o.sum() == ((100 - (bands - 1)) * (100 - (bands - 1)) * (i + 1))

{yirgacheffe-1.9.3 → yirgacheffe-1.9.5}/tests/test_openers.py

@@ -264,3 +264,29 @@ def test_constant() -> None:
             expected = np.full((20, 20), 42.0)
             actual = result.read_array(0, 0, 20, 20)
             assert (expected == actual).all()
+
+def test_create_simple_float() -> None:
+    projection = MapProjection(WGS_84_PROJECTION, 1.0, -1.0)
+    data = np.array([[1.0, 2.0, 3.0, 4.0], [5.0, 6.0, 7.0, 8.0]])
+    with yg.from_array(data, (-2.0, 1.0), projection) as layer:
+        expected_area = Area(left=-2.0, right=2.0, top=1.0, bottom=-1.0)
+
+        assert layer.map_projection == projection
+        assert layer.area == expected_area
+        assert layer.datatype == DataType.Float64
+
+        actual = layer.read_array(0, 0, 4, 2)
+        assert (data == actual).all()
+
+def test_create_simple_direct_projection() -> None:
+    expected_projection = MapProjection(WGS_84_PROJECTION, 1.0, -1.0)
+    data = np.array([[1, 2, 3, 4], [5, 6, 7, 8]])
+    with yg.from_array(data, (-2.0, 1.0), (WGS_84_PROJECTION, (1.0, -1.0))) as layer:
+        expected_area = Area(left=-2.0, right=2.0, top=1.0, bottom=-1.0)
+
+        assert layer.map_projection == expected_projection
+        assert layer.area == expected_area
+        assert layer.datatype == DataType.Int64
+
+        actual = layer.read_array(0, 0, 4, 2)
+        assert (data == actual).all()

{yirgacheffe-1.9.3 → yirgacheffe-1.9.5}/tests/test_operators.py

@@ -7,7 +7,7 @@ import numpy as np
 import pytest
 import torch
 
-import yirgacheffe
+import yirgacheffe as yg
 from yirgacheffe.window import Area, PixelScale
 from yirgacheffe.layers import ConstantLayer, RasterLayer, VectorLayer
 from yirgacheffe.operators import DataType
@@ -91,6 +91,29 @@ def test_add_byte_layers_with_callback(skip, expected_steps) -> None:
 
     assert callback_positions == expected_steps
 
+@pytest.mark.parametrize("skip,expected_steps", [
+    (1, [0.0, 0.5, 1.0]),
+    (2, [0.0, 1.0]),
+])
+def test_add_byte_layers_to_geotiff_with_callback(skip, expected_steps) -> None:
+    data1 = np.array([[1, 2, 3, 4], [5, 6, 7, 8]]).astype(np.uint8)
+    data2 = np.array([[10, 20, 30, 40], [50, 60, 70, 80]]).astype(np.uint8)
+
+    with (
+        RasterLayer(gdal_dataset_with_data((0.0, 0.0), 0.02, data1)) as layer1,
+        RasterLayer(gdal_dataset_with_data((0.0, 0.0), 0.02, data2)) as layer2,
+    ):
+        callback_positions: list[float] = []
+
+        comp = layer1 + layer2
+        comp.ystep = skip
+
+        with tempfile.TemporaryDirectory() as tempdir:
+            filename = os.path.join(tempdir, "test.tif")
+            comp.to_geotiff(filename, callback=callback_positions.append)
+
+        assert callback_positions == expected_steps
+
 def test_sub_byte_layers() -> None:
     data1 = np.array([[10, 20, 30, 40], [50, 60, 70, 80]])
     data2 = np.array([[1, 2, 3, 4], [5, 6, 7, 8]])
@@ -596,7 +619,7 @@ def test_direct_layer_save_and_sum() -> None:
     assert (data1 == actual_data).all()
     assert expected_sum == actual_sum
 
-@pytest.mark.skipif(yirgacheffe._backends.BACKEND != "NUMPY", reason="Only applies for numpy")
+@pytest.mark.skipif(yg._backends.BACKEND != "NUMPY", reason="Only applies for numpy")
 def test_add_to_float_layer_by_np_array() -> None:
     data1 = np.array([[1.0, 2.0, 3.0, 4.0], [5.0, 6.0, 7.0, 8.0]])
     layer1 = RasterLayer(gdal_dataset_with_data((0.0, 0.0), 0.02, data1))
@@ -631,7 +654,7 @@ def test_write_mulitband_raster() -> None:
 
             assert (expected == actual).all()
 
-@pytest.mark.skipif(yirgacheffe._backends.BACKEND != "NUMPY", reason="Only applies for numpy")
+@pytest.mark.skipif(yg._backends.BACKEND != "NUMPY", reason="Only applies for numpy")
 def test_save_and_sum_float32(monkeypatch) -> None:
     random.seed(42)
     data = []
@@ -650,12 +673,12 @@ def test_save_and_sum_float32(monkeypatch) -> None:
 
     with monkeypatch.context() as m:
         for blocksize in range(1,11):
-            m.setattr(yirgacheffe.constants, "YSTEP", blocksize)
+            m.setattr(yg.constants, "YSTEP", blocksize)
             with RasterLayer.empty_raster_layer_like(layer1) as store:
                 actual = layer1.save(store, and_sum=True)
             assert expected == actual
 
-@pytest.mark.skipif(yirgacheffe._backends.BACKEND != "NUMPY", reason="Only applies for numpy")
+@pytest.mark.skipif(yg._backends.BACKEND != "NUMPY", reason="Only applies for numpy")
 def test_parallel_save_and_sum_float32(monkeypatch) -> None:
     random.seed(42)
     data = []
@@ -678,12 +701,12 @@ def test_parallel_save_and_sum_float32(monkeypatch) -> None:
 
         with monkeypatch.context() as m:
             for blocksize in range(1,11):
-                m.setattr(yirgacheffe.constants, "YSTEP", blocksize)
+                m.setattr(yg.constants, "YSTEP", blocksize)
                 with RasterLayer.empty_raster_layer_like(layer1) as store:
                     actual = layer1.parallel_save(store, and_sum=True)
                 assert expected == actual
 
-@pytest.mark.skipif(yirgacheffe._backends.BACKEND != "NUMPY", reason="Only applies for numpy")
+@pytest.mark.skipif(yg._backends.BACKEND != "NUMPY", reason="Only applies for numpy")
 def test_sum_float32(monkeypatch) -> None:
     random.seed(42)
     data = []
@@ -702,7 +725,7 @@ def test_sum_float32(monkeypatch) -> None:
 
     with monkeypatch.context() as m:
         for blocksize in range(1,11):
-            m.setattr(yirgacheffe.constants, "YSTEP", blocksize)
+            m.setattr(yg.constants, "YSTEP", blocksize)
             actual = layer1.sum()
             assert expected == actual
 
@@ -1488,21 +1511,21 @@ def test_to_geotiff_single_thread_and_sum() -> None:
             actual = result.read_array(0, 0, 4, 2)
             assert (expected == actual).all()
 
-@pytest.mark.skipif(yirgacheffe._backends.BACKEND != "NUMPY", reason="Only applies for numpy")
+@pytest.mark.skipif(yg._backends.BACKEND != "NUMPY", reason="Only applies for numpy")
 @pytest.mark.parametrize("parallelism", [
     2,
     True,
 ])
 def test_to_geotiff_parallel_thread(monkeypatch, parallelism) -> None:
     with monkeypatch.context() as m:
-        m.setattr(yirgacheffe.constants, "YSTEP", 1)
+        m.setattr(yg.constants, "YSTEP", 1)
         m.setattr(LayerOperation, "save", None)
         with tempfile.TemporaryDirectory() as tempdir:
             data1 = np.array([[1, 2, 3, 4], [5, 6, 7, 8]])
             src_filename = os.path.join("src.tif")
             dataset = gdal_dataset_with_data((0.0, 0.0), 0.02, data1, filename=src_filename)
             dataset.Close()
-            with yirgacheffe.read_raster(src_filename) as layer1:
+            with yg.read_raster(src_filename) as layer1:
                 calc = layer1 * 2
                 filename = os.path.join(tempdir, "test.tif")
                 calc.to_geotiff(filename, parallelism=parallelism)
@@ -1512,27 +1535,30 @@ def test_to_geotiff_parallel_thread(monkeypatch, parallelism) -> None:
                     actual = result.read_array(0, 0, 4, 2)
                     assert (expected == actual).all()
 
-@pytest.mark.skipif(yirgacheffe._backends.BACKEND != "NUMPY", reason="Only applies for numpy")
+@pytest.mark.skipif(yg._backends.BACKEND != "NUMPY", reason="Only applies for numpy")
 @pytest.mark.parametrize("parallelism", [
     2,
     True,
 ])
 def test_to_geotiff_parallel_thread_and_sum(monkeypatch, parallelism) -> None:
     with monkeypatch.context() as m:
-        m.setattr(yirgacheffe.constants, "YSTEP", 1)
+        m.setattr(yg.constants, "YSTEP", 1)
         m.setattr(LayerOperation, "save", None)
         with tempfile.TemporaryDirectory() as tempdir:
             data1 = np.array([[1, 2, 3, 4], [5, 6, 7, 8]])
             src_filename = os.path.join("src.tif")
             dataset = gdal_dataset_with_data((0.0, 0.0), 0.02, data1, filename=src_filename)
             dataset.Close()
-            with yirgacheffe.read_raster(src_filename) as layer1:
+            with yg.read_raster(src_filename) as layer1:
                 filename = os.path.join(tempdir, "test.tif")
                 calc = layer1 * 2
-                actual_sum = calc.to_geotiff(filename, and_sum=True, parallelism=parallelism)
+                steps: list[float] = []
+                actual_sum = calc.to_geotiff(filename, and_sum=True, parallelism=parallelism, callback=steps.append)
 
                 assert (data1.sum() * 2) == actual_sum
 
+                assert steps == [0.0, 0.5, 1.0]
+
                 with RasterLayer.layer_from_file(filename) as result:
                     expected = data1 * 2
                     actual = result.read_array(0, 0, 4, 2)
@@ -1548,7 +1574,7 @@ def test_raster_and_vector() -> None:
         make_vectors_with_id(42, {area}, path)
         assert path.exists()
 
-        vector = VectorLayer.layer_from_file(path, None, PixelScale(1.0, -1.0), yirgacheffe.WGS_84_PROJECTION)
+        vector = VectorLayer.layer_from_file(path, None, PixelScale(1.0, -1.0), yg.WGS_84_PROJECTION)
 
         calc = raster * vector
         assert calc.sum() > 0.0
@@ -1564,7 +1590,7 @@ def test_raster_and_vector_mixed_projection() -> None:
         make_vectors_with_id(42, {area}, path)
         assert path.exists()
 
-        vector = VectorLayer.layer_from_file(path, None, PixelScale(1.0, -1.0), yirgacheffe.WGS_84_PROJECTION)
+        vector = VectorLayer.layer_from_file(path, None, PixelScale(1.0, -1.0), yg.WGS_84_PROJECTION)
 
         with pytest.raises(ValueError):
             _ = raster * vector
@@ -1600,7 +1626,7 @@ def test_isnan() -> None:
 @pytest.mark.parametrize("blocksize", [1, 2, 4, 8])
 def test_add_byte_layers_read_array_all(monkeypatch, blocksize) -> None:
     with monkeypatch.context() as m:
-        m.setattr(yirgacheffe.constants, "YSTEP", blocksize)
+        m.setattr(yg.constants, "YSTEP", blocksize)
         data1 = np.array([[1, 2, 3, 4], [5, 6, 7, 8]])
         data2 = np.array([[10, 20, 30, 40], [50, 60, 70, 80]])
 
@@ -1616,7 +1642,7 @@ def test_add_byte_layers_read_array_all(monkeypatch, blocksize) -> None:
 @pytest.mark.parametrize("blocksize", [1, 2, 4, 8])
 def test_add_byte_layers_read_array_partial_horizontal(monkeypatch, blocksize) -> None:
     with monkeypatch.context() as m:
-        m.setattr(yirgacheffe.constants, "YSTEP", blocksize)
+        m.setattr(yg.constants, "YSTEP", blocksize)
         data1 = np.array([[1, 2, 3, 4], [5, 6, 7, 8]])
         data2 = np.array([[10, 20, 30, 40], [50, 60, 70, 80]])
 
@@ -1632,7 +1658,7 @@ def test_add_byte_layers_read_array_partial_horizontal(monkeypatch, blocksize) -
 @pytest.mark.parametrize("blocksize", [1, 2, 4, 8])
 def test_add_byte_layers_read_array_partial_vertical(monkeypatch, blocksize) -> None:
     with monkeypatch.context() as m:
-        m.setattr(yirgacheffe.constants, "YSTEP", blocksize)
+        m.setattr(yg.constants, "YSTEP", blocksize)
         data1 = np.array([[1, 2], [3, 4], [5, 6], [7, 8]])
         data2 = np.array([[10, 20], [30, 40], [50, 60], [70, 80]])
 
@@ -1648,7 +1674,7 @@ def test_add_byte_layers_read_array_partial_vertical(monkeypatch, blocksize) ->
 @pytest.mark.parametrize("blocksize", [1, 2, 4, 8])
 def test_add_byte_layers_read_array_partial(monkeypatch, blocksize) -> None:
     with monkeypatch.context() as m:
-        m.setattr(yirgacheffe.constants, "YSTEP", blocksize)
+        m.setattr(yg.constants, "YSTEP", blocksize)
         data1 = np.array([[1, 2, 3, 4], [5, 6, 7, 8], [9, 10, 11, 12], [13, 14, 15, 16]])
         data2 = np.array([[10, 10, 10, 10], [20, 20, 20, 20], [30, 30, 30, 30], [40, 40, 40, 40]])
 
@@ -1664,13 +1690,14 @@ def test_add_byte_layers_read_array_partial(monkeypatch, blocksize) -> None:
 @pytest.mark.parametrize("blocksize", [1, 2, 4, 8])
 def test_add_byte_layers_read_array_superset(monkeypatch, blocksize) -> None:
     with monkeypatch.context() as m:
-        m.setattr(yirgacheffe.constants, "YSTEP", blocksize)
+        m.setattr(yg.constants, "YSTEP", blocksize)
         data1 = np.array([[1, 2, 3, 4], [5, 6, 7, 8], [9, 10, 11, 12], [13, 14, 15, 16]])
         data2 = np.array([[10, 10, 10, 10], [20, 20, 20, 20], [30, 30, 30, 30], [40, 40, 40, 40]])
 
+        projection = yg.MapProjection("epsg:4326", 0.02, -0.02)
         with (
-            RasterLayer(gdal_dataset_with_data((0.0, 0.0), 0.02, data1)) as layer1,
-            RasterLayer(gdal_dataset_with_data((0.0, 0.0), 0.02, data2)) as layer2,
+            yg.from_array(data1, (0.0, 0.0), projection) as layer1,
+            yg.from_array(data2, (0.0, 0.0), projection) as layer2,
         ):
             comp = layer1 + layer2
             inner_expected = data1 + data2

{yirgacheffe-1.9.3 → yirgacheffe-1.9.5}/tests/test_reduce.py

@@ -3,8 +3,7 @@ import operator
 
 import numpy as np
 
-from yirgacheffe.layers import RasterLayer
-from tests.helpers import gdal_dataset_with_data
+import yirgacheffe as yg
 
 def test_add_similar_layers() -> None:
     data = [
@@ -13,7 +12,9 @@ def test_add_similar_layers() -> None:
         np.array([[100, 200, 300, 400], [500, 600, 700, 800]]),
     ]
 
-    layers = [RasterLayer(gdal_dataset_with_data((0,0), 1.0, x)) for x in data]
+    origin = (0.0, 0.0)
+    map_projection = yg.MapProjection("epsg:4326", 1.0, -1.0)
+    layers = [yg.from_array(x, origin, map_projection) for x in data]
 
     summed_layers = reduce(operator.add, layers)
     actual = summed_layers.read_array(0, 0, 4, 2)

{yirgacheffe-1.9.3 → yirgacheffe-1.9.5}/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-1.9.3 → yirgacheffe-1.9.5}/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-1.9.3 → yirgacheffe-1.9.5}/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-1.9.3 → yirgacheffe-1.9.5}/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-1.9.3 → yirgacheffe-1.9.5}/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-1.9.3 → yirgacheffe-1.9.5}/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 → yirgacheffe-1.9.5}/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 → yirgacheffe-1.9.5/yirgacheffe.egg-info}/PKG-INFO

@@ -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.