rusterize 0.4.0__cp311-abi3-manylinux_2_28_ppc64le.whl → 0.4.1__cp311-abi3-manylinux_2_28_ppc64le.whl

rusterize/__init__.py

@@ -1,14 +1,15 @@
 from __future__ import annotations
-import importlib.metadata
 
+import importlib.metadata
 from types import NoneType
 from typing import List, Tuple
 
 import numpy as np
 import polars as pl
-from geopandas import GeoDataFrame
 import rioxarray
+from geopandas import GeoDataFrame
 from xarray import DataArray
+
 from .rusterize import _rusterize
 
 __version__ = importlib.metadata.version("rusterize")
@@ -16,6 +17,7 @@ __version__ = importlib.metadata.version("rusterize")
 
 def rusterize(
     gdf: GeoDataFrame,
+    like: DataArray | None = None,
     res: Tuple | List | None = None,
     out_shape: Tuple | List | None = None,
     extent: Tuple | List | None = None,
@@ -31,6 +33,7 @@ def rusterize(
 
     Args:
         :param gdf: geopandas dataframe to rasterize.
+        :param like: array to use as blueprint for spatial matching (resolution, shape, extent). Mutually exlusive with res, out_shape, and extent.
         :param res: (xres, yres) for rasterized data.
         :param out_shape: (nrows, ncols) for regularized output shape.
         :param extent: (xmin, xmax, ymin, ymax) for regularized extent.
@@ -46,17 +49,20 @@ def rusterize(
 
     Notes:
         When any of `res`, `out_shape`, or `extent` is not provided, it is inferred from the other arguments when applicable.
+        If `like` is specified, `res`, `out_shape`, and `extent` are inferred from the `like` DataArray.
         Unless `extent` is specified, a half-pixel buffer is applied to avoid missing points on the border.
         The logics dictating the final spatial properties of the rasterized geometries follow those of GDAL.
-        
+
         If `field` is not in `gdf`, then a default `burn` value of 1 is rasterized.
-        
+
         A `None` value for `dtype` corresponds to the default of that dtype. An illegal value for a dtype will be replaced with the default of
         that dtype. For example, a `background=np.nan` for `dtype="uint8"` will become `background=0`, where `0` is the default for `uint8`.
     """
     # type checks
     if not isinstance(gdf, GeoDataFrame):
         raise TypeError("`gdf` must be a geopandas dataframe.")
+    if not isinstance(like, (DataArray, NoneType)):
+        raise TypeError("`'ike' must be a xarray.DataArray")
     if not isinstance(res, (tuple, list, NoneType)):
         raise TypeError("`resolution` must be a tuple or list of (x, y).")
     if not isinstance(out_shape, (tuple, list, NoneType)):
@@ -74,26 +80,39 @@ def rusterize(
     if not isinstance(background, (int, float, NoneType)):
         raise TypeError("`background` must be integer, float, or None.")
     if not isinstance(dtype, str):
-        raise TypeError("`dtype` must be a one of uint8, uint16, uint32, uint64, int8, int16, int32, int64, float32, float64")
-
-    # value checks
-    if not res and not out_shape and not extent:
-        raise ValueError("One of `res`, `out_shape`, or `extent` must be provided.")
-    if extent and not res and not out_shape:
-        raise ValueError("Must also specify `res` or `out_shape` with extent.")
-    if res and (len(res) != 2 or any(r <= 0 for r in res) or any(not isinstance(r, (int, float)) for r in res)):
-        raise ValueError("Resolution must be 2 positive numbers.")
-    if out_shape and (len(out_shape) != 2 or any(s <= 0 for s in out_shape) or any(not isinstance(s, int) for s in out_shape)):
-        raise ValueError("Output shape must be 2 positive integers.")
-    if extent and len(extent) != 4:
-        raise ValueError("Extent must be 4 numbers (xmin, ymin, xmax, ymax).")
+        raise TypeError(
+            "`dtype` must be a one of uint8, uint16, uint32, uint64, int8, int16, int32, int64, float32, float64"
+        )
+
+    # value checks and defaults
     if field and burn:
         raise ValueError("Only one of `field` or `burn` can be specified.")
+    if like is not None:
+        if any((res, out_shape, extent)):
+            raise ValueError("`like` is mutually exclusive with `res`, `out_shape`, and `extent`.")
+        else:
+            affine = like.rio.transform()
+            _res = (affine.a, abs(affine.e))
+            _shape = like.squeeze().shape
+            _bounds, _has_extent = like.rio.bounds(), True
+    else:
+        if not res and not out_shape and not extent:
+            raise ValueError("One of `res`, `out_shape`, or `extent` must be provided.")
+        if extent and not res and not out_shape:
+            raise ValueError("Must also specify `res` or `out_shape` with extent.")
+        if res and (len(res) != 2 or any(r <= 0 for r in res) or any(not isinstance(r, (int, float)) for r in res)):
+            raise ValueError("`res` must be 2 positive numbers.")
+        if out_shape and (
+            len(out_shape) != 2 or any(s <= 0 for s in out_shape) or any(not isinstance(s, int) for s in out_shape)
+        ):
+            raise ValueError("`out_shape` must be 2 positive integers.")
+        if extent and len(extent) != 4:
+            raise ValueError("`extent` must be a tuple or list of (xmin, ymin, xmax, ymax).")
 
-    # defaults
-    _res = res if res else (0, 0)
-    _shape = out_shape if out_shape else (0, 0)
-    (_bounds, _has_extent) = (extent, True) if extent else (gdf.total_bounds, False)
+        # defaults
+        _res = res if res else (0, 0)
+        _shape = out_shape if out_shape else (0, 0)
+        (_bounds, _has_extent) = (extent, True) if extent else (gdf.total_bounds, False)
 
     # RasterInfo
     raster_info = {
@@ -113,7 +132,7 @@ def rusterize(
     try:
         df = pl.from_pandas(gdf[cols]) if cols else None
     except KeyError as e:
-        raise KeyError("Column not found in GeoDataFrame") from e
+        raise KeyError("Column not found in GeoDataFrame.") from e
 
     # rusterize
     r = _rusterize(gdf.geometry, raster_info, fun, df, field, by, burn, background, dtype)

{rusterize-0.4.0.dist-info → rusterize-0.4.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rusterize
-Version: 0.4.0
+Version: 0.4.1
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Rust
@@ -25,13 +25,13 @@ High performance rasterization tool for Python built in Rust. This
 repository stems from the [fasterize](https://github.com/ecohealthalliance/fasterize.git) package built in C++
 for R and ports parts of the logics into Python with a Rust backend, in addition to some useful improvements (see [API](#API)).
 
-**rusterize** is designed to work on *(multi)polygons* and *(multi)linestrings*, even when they are nested inside complex geometry collections. Functionally, it takes an input [geopandas](https://geopandas.org/en/stable/) dataframe and returns a [xarray](https://docs.xarray.dev/en/stable/). 
+**rusterize** is designed to work on _(multi)polygons_ and _(multi)linestrings_, even when they are nested inside complex geometry collections. Functionally, it takes an input [geopandas](https://geopandas.org/en/stable/) dataframe and returns a [xarray](https://docs.xarray.dev/en/stable/).
 
 # Installation
 
 Install the current version with pip:
 
-``` shell
+```shell
 pip install rusterize
 ```
 
@@ -43,7 +43,7 @@ package. For this to work, you’ll need to have [Rust](https://www.rust-lang.or
 [cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html)
 installed.
 
-``` shell
+```shell
 # Clone repo
 git clone https://github.com/<username>/rusterize.git
 cd rusterize
@@ -62,25 +62,29 @@ maturin develop --profile dist-release
 
 This package has a simple API:
 
-``` python
+```python
 from rusterize import rusterize
 
 # gdf = <import/modify dataframe as needed>
 
 # rusterize
-rusterize(gdf,
-          res=(30, 30),
-          out_shape=(10, 10)
-          extent=(0, 10, 10, 20)
-          field="field",
-          by="by",
-          burn=None,
-          fun="sum",
-          background=0,
-          dtype="uint8") 
+rusterize(
+    gdf,
+    like=None,
+    res=(30, 30),
+    out_shape=(10, 10),
+    extent=(0, 10, 10, 20),
+    field="field",
+    by="by",
+    burn=None,
+    fun="sum",
+    background=0,
+    dtype="uint8"
+)
 ```
 
 - `gdf`: geopandas dataframe to rasterize
+- `like`: xr.DataArray to use as template for `res`, `out_shape`, and `extent`. Mutually exclusive with these parameters (default: `None`)
 - `res`: (xres, yres) for desired resolution (default: `None`)
 - `out_shape`: (nrows, ncols) for desired output shape (default: `None`)
 - `extent`: (xmin, ymin, xmax, ymax) for desired output extent (default: `None`)
@@ -103,7 +107,7 @@ shape, the extent is maintained. This mimics the logics of `gdal_rasterize`.
 returns a dictionary that is converted to a xarray on the Python side
 for simpliicty.
 
-``` python
+```python
 from rusterize import rusterize
 import geopandas as gpd
 from shapely import wkt
@@ -144,7 +148,7 @@ plt.show()
 
 **rusterize** is fast! Let’s try it on small and large datasets.
 
-``` python
+```python
 from rusterize import rusterize
 import geopandas as gpd
 import requests
@@ -158,7 +162,7 @@ response = requests.get(url)
 # unzip
 with zipfile.ZipFile(BytesIO(response.content), 'r') as zip_ref:
     zip_ref.extractall()
-    
+
 # read
 gdf_large = gpd.read_file("Mammals_Terrestrial/Mammals_Terrestrial.shp")
 
@@ -168,12 +172,13 @@ gdf_small = gdf_large.iloc[:1000, :]
 # rusterize at 1/6 degree resolution
 def test_large(benchmark):
   benchmark(rusterize, gdf_large, res=(1/6, 1/6), fun="sum")
-   
+
 def test_small(benchmark):
-  benchmark(rusterize, gdf_small, res=(1/6, 1/6), fun="sum")  
+  benchmark(rusterize, gdf_small, res=(1/6, 1/6), fun="sum")
 ```
 
 Then you can run it with [pytest](https://docs.pytest.org/en/stable/) and [pytest-benchmark](https://pytest-benchmark.readthedocs.io/en/stable/):
+
 ```
 pytest <python file> --benchmark-min-rounds=20 --benchmark-time-unit='s'
 
@@ -184,8 +189,10 @@ rusterize_small       0.0791    0.0899   0.0812  0.0027   0.0803  0.0020       2
 rusterize_large     1.379545    1.4474   1.4006  0.0178   1.3966  0.0214       5;1   0.7140     20          1
 -------------------------------------------------------------------------------------------------------------
 ```
+
 And fasterize:
-``` r
+
+```r
 library(sf)
 library(raster)
 library(fasterize)
@@ -204,13 +211,16 @@ microbenchmark(
   unit='s'
 )
 ```
+
 ```
 Unit: seconds
             expr       min         lq       mean     median        uq        max neval
  fasterize_small 0.4741043  0.4926114  0.5191707  0.5193289  0.536741  0.5859029    20
  fasterize_large 9.2199426 10.3595465 10.6653139 10.5369429 11.025771 11.7944567    20
 ```
+
 And on an even larger datasets? Here we use a layer from the province of Quebec, Canada representing ~2M polygons of forest stands, rasterized at 30 meters (20 rounds) with no field value and pixel function `any`. The comparison with `gdal_rasterize` was run with `hyperfine --runs 20 "gdal_rasterize -tr 30 30 -burn 1 <data_in> <data_out>"`.
+
 ```
 # rusterize
 --------------------------------------------- benchmark: 1 tests --------------------------------------------
@@ -228,7 +238,9 @@ Unit: seconds
 Time (mean ± σ):      5.495 s ±  0.038 s    [User: 4.268 s, System: 1.225 s]
 Range (min … max):    5.452 s …  5.623 s    20 runs
 ```
+
 In terms of (multi)line rasterization speed, here's a benchmark against `gdal_rasterize` using a layer from the province of Quebec, Canada, representing a subset of the road network for a total of ~535K multilinestrings.
+
 ```
 # rusterize
 --------------------------------------------- benchmark: 1 tests --------------------------------------------
@@ -241,14 +253,17 @@ test                  4.5272   5.9488   4.7171  0.3236   4.6360  0.1680       2;
 Time (mean ± σ):      8.719 s ±  0.063 s    [User: 3.782 s, System: 4.917 s]
 Range (min … max):    8.658 s …  8.874 s    20 runs
 ```
+
 # Comparison with other tools
 
 While **rusterize** is fast, there are other fast alternatives out there, including `GDAL`, `rasterio` and `geocube`. However, **rusterize** allows for a seamless, Rust-native processing with similar or lower memory footprint that doesn't require you to leave Python, and returns the geoinformation you need for downstream processing with ample control over resolution, shape, extent, and data type.
 
 The following is a time comparison on a single run on the same forest stands dataset used earlier.
+
 ```
 rusterize:    5.9 sec
 rasterio:     68  sec (but no spatial information)
 fasterize:    157 sec (including raster creation)
 geocube:      260 sec (larger memory footprint)
 ```
+

rusterize-0.4.1.dist-info/RECORD

@@ -0,0 +1,6 @@
+rusterize-0.4.1.dist-info/METADATA,sha256=1kAxrvUCGH9PGUTwL0b40mas-5YyNN3w8QIIxaBtXW4,11278
+rusterize-0.4.1.dist-info/WHEEL,sha256=LyKrmraG_uSXY5vhpX0CJs5HieuGNOxWFsl0o305mFk,108
+rusterize-0.4.1.dist-info/licenses/LICENSE,sha256=v-2DqBji_azGEWFDxBhw-CNIRu8450vBbloLx6UNqLU,1108
+rusterize/__init__.py,sha256=u5ZbtujqvgUALd446NMUP28W7csKbgg-qb9B0GRt9xU,6409
+rusterize/rusterize.abi3.so,sha256=gqoznfyypqLHCu_AvHpItWcDS51oiMVMvA68XPjThRQ,52167072
+rusterize-0.4.1.dist-info/RECORD,,

{rusterize-0.4.0.dist-info → rusterize-0.4.1.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: maturin (1.9.3)
+Generator: maturin (1.9.4)
 Root-Is-Purelib: false
 Tag: cp311-abi3-manylinux_2_28_ppc64le

rusterize-0.4.0.dist-info/RECORD

@@ -1,6 +0,0 @@
-rusterize-0.4.0.dist-info/METADATA,sha256=VxdEZ9jhsBsBCzPY-yZiktAmNs4wuSWEe3GpU863CTQ,11176
-rusterize-0.4.0.dist-info/WHEEL,sha256=MGaQjBHAphO6IVR063SFNWIT-ZlGUh0_fKN0-9trTkw,108
-rusterize-0.4.0.dist-info/licenses/LICENSE,sha256=v-2DqBji_azGEWFDxBhw-CNIRu8450vBbloLx6UNqLU,1108
-rusterize/__init__.py,sha256=TZvnGqurMBCNrnTfdtjkFhQofqUk-w7TO19JhB5m1OQ,5525
-rusterize/rusterize.abi3.so,sha256=8XDkTy4fMGQeErO_QYQgg50UcmAgX_v-u54LHUMcgyo,48538216
-rusterize-0.4.0.dist-info/RECORD,,