rusterize 0.1.0__cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl → 0.1.1__cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

rusterize/core.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from types import NoneType
 from typing import Any, Dict, Optional, Tuple, Union
 
 import polars as pl
@@ -10,7 +11,9 @@ from .rusterize import _rusterize
 
 
 def rusterize(gdf: DataFrame,
-              res: Union[Tuple[int, ...], Tuple[float, ...]],
+              res: Optional[Union[Tuple[int, ...], Tuple[float, ...]]] = None,
+              out_shape: Optional[Union[Tuple[int, ...]]] = None,
+              extent: Optional[Union[Tuple[int, ...], Tuple[float, ...]]] = None,
               field: Optional[str] = None,
               by: Optional[str] = None,
               fun: str = "last",
@@ -20,47 +23,71 @@ def rusterize(gdf: DataFrame,
     Fast geopandas rasterization into xarray.DataArray
 
     Args:
-    :param gdf: geopandas dataframe to rasterize.
-    :param res: tuple of (xres, yres) for rasterized data.
-    :param field: field to rasterize. Default is None.
-    :param by: column to rasterize, assigns each unique value to a layer in the stack based on field. Default is None.
-    :param fun: pixel function to use, see fasterize for options. Default is `last`.
-    :param background: background value in final raster. Default is None.
+        :param gdf: geopandas dataframe to rasterize.
+        :param res: tuple of (xres, yres) for rasterized data.
+        :param out_shape: tuple of (nrows, ncols) for regularized output shape.
+        :param extent: tuple of (xmin, xmax, ymin, ymax) for regularized extent.
+        :param field: field to rasterize. Default is None.
+        :param by: column to rasterize, assigns each unique value to a layer in the stack based on field. Default is None.
+        :param fun: pixel function to use, see fasterize for options. Default is `last`.
+        :param background: background value in final raster. Default is None.
 
     Returns:
-        Dictionary containing rasterized geometries and spatial attributes to build a xarray.DataArray.
+        Rasterized xarray.DataArray.
+
+    Note:
+        When any of `res`, `out_shape`, or `extent` is not provided, it is inferred from the other arguments when applicable.
+        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.
     """
     # type checks
     if not isinstance(gdf, DataFrame):
         raise TypeError("Must pass a valid geopandas dataframe.")
-    if not isinstance(field, (str, type(None))):
+    if not isinstance(res, (tuple, NoneType)):
+        raise TypeError("Must pass a valid resolution tuple (x, y).")
+    if not isinstance(out_shape, (tuple, NoneType)):
+        raise TypeError("Must pass a valid output shape tuple (nrows, ncols).")
+    if not isinstance(extent, (tuple, NoneType)):
+        raise TypeError("Must pass a valid extent tuple (xmin, ymin, xmax, ymax).")
+    if not isinstance(field, (str, NoneType)):
         raise TypeError("Must pass a valid string to field.")
-    if not isinstance(by, (str, type(None))):
+    if not isinstance(by, (str, NoneType)):
         raise TypeError("Must pass a valid string to by.")
-    if not isinstance(res, tuple):
-        raise TypeError("Must pass a valid resolution tuple (x, y).")
     if not isinstance(fun, str):
         raise TypeError("Must pass a valid string to pixel_fn. Select only of sum, first, last, min, max, count, or any.")
-    if not isinstance(background, (int, float, type(None))):
+    if not isinstance(background, (int, float, NoneType)):
         raise TypeError("Must pass a valid background type.")
 
     # value check
+    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).")
     if by and not field:
         raise ValueError("If by is specified, field must also be specified.")
-    if len(res) != 2 or any((res[0], res[1])) <= 0 or not isinstance(res[0], type(res[1])):
-        raise ValueError("Must pass valid resolution tuple of values of consistent dtype.")
+
+    # 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
-    bounds = gdf.total_bounds
     raster_info = {
-        "xmin": bounds[0],
-        "ymin": bounds[1],
-        "xmax": bounds[2],
-        "ymax": bounds[3],
-        "xres": res[0],
-        "yres": res[1],
-        "nrows": 0,
-        "ncols": 0
+        "xmin": _bounds[0],
+        "ymin": _bounds[1],
+        "xmax": _bounds[2],
+        "ymax": _bounds[3],
+        "xres": _res[0],
+        "yres": _res[1],
+        "nrows": _shape[0],
+        "ncols": _shape[1],
+        "has_extent": has_extent
     }
 
     # extract columns of interest and convert to polars

{rusterize-0.1.0.dist-info → rusterize-0.1.1.dist-info}/METADATA

@@ -1,19 +1,19 @@
 Metadata-Version: 2.4
 Name: rusterize
-Version: 0.1.0
+Version: 0.1.1
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
-Requires-Dist: geopandas >=1.0.1
-Requires-Dist: pandas >=2.2.3
-Requires-Dist: pyarrow >=18.1.0
-Requires-Dist: polars >=1.19.0
-Requires-Dist: xarray >=2025.1.1
-Requires-Dist: rioxarray >=0.18.2
+Requires-Dist: geopandas>=1.0.1
+Requires-Dist: pandas>=2.2.3
+Requires-Dist: pyarrow>=18.1.0
+Requires-Dist: polars>=1.19.0
+Requires-Dist: xarray>=2025.1.1
+Requires-Dist: rioxarray>=0.18.2
 License-File: LICENSE
-Summary: High performance rasterization tool for Python build in Rust
+Summary: High performance rasterization tool for Python built in Rust
 Keywords: fast,raster
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
@@ -21,9 +21,9 @@ Project-URL: repository, https://github.com/ttrotto/rusterize
 
 # rusterize
 
-High performance rasterization tool for python built in Rust. This
-repository is heavily based on the [**fasterize**](https://github.com/ecohealthalliance/fasterize.git) package built in C++
-for R. This version ports it to Python with a Rust backend.
+High performance rasterization tool for Python built in Rust. This
+repository is heavily based on the [fasterize](https://github.com/ecohealthalliance/fasterize.git) package built in C++
+for R. This version ports it to Python with a Rust backend, with some useful improvements.
 
 Functionally, it takes an input [geopandas](https://geopandas.org/en/stable/)
 dataframes and returns a [xarray](https://docs.xarray.dev/en/stable/). It
@@ -34,7 +34,7 @@ tighly mirrors the processing routine of fasterize, so it works only on
 
 Install the current version with pip:
 
-``` {shell}
+``` shell
 pip install rusterize
 ```
 
@@ -46,7 +46,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
@@ -65,22 +65,26 @@ maturin develop --profile dist-release
 
 This function has a simple API:
 
-``` {shell}
+``` python
 from rusterize.core import rusterize
 
 # gdf = <import datasets as needed>
 
 # rusterize
 rusterize(gdf,
-          (30, 30),
-          "field",
-          "by",
-          "sum",
-          0) 
+          res=(30, 30),
+          out_shape=(10, 10)
+          extent=(0, 300, 0, 300)
+          field="field",
+          by="by",
+          fun="sum",
+          background=0) 
 ```
 
 - `gdf`: geopandas dataframe to rasterize
-- `res`: tuple of (xres, yres) for final resolution
+- `res`: tuple of (xres, yres) for desired resolution
+- `out_shape`: tuple of (nrows, ncols) for desired output shape
+- `extent`: tuple of (xmin, ymin, xmax, ymax) for desired output extent
 - `field`: field to rasterize. Default is None (a value of `1` is rasterized).
 - `by`: column to rasterize. Assigns each group to a band in the
   stack. Values are taken from `field`. Default is None
@@ -88,10 +92,16 @@ rusterize(gdf,
   `last`. Available options are `sum`, `first`, `last`, `min`, `max`, `count`, or `any`
 - `background`: background value in final raster. Default is None (NaN)
 
+Note that control over the desired extent is not as strict as for resolution and shape. That is,
+when resolution, output shape, and extent are specified, priority is given to resolution and shape.
+So, extent is not guaranteed, but resolution and shape are. If extent is not given, it is taken
+from the polygons and is not modified, unless you specify a resolution value. If you only specify an output
+shape, the extent is maintained. This mimics the logics of `gdal_rasterize`.
+
 # Usage
 
 **rusterize** consists of a single function `rusterize()`. The Rust implementation
-returns an array that is then converted to a xarray on the Python side
+returns an array that is converted to a xarray on the Python side
 for simpliicty.
 
 ``` python
@@ -127,12 +137,11 @@ output.plot.imshow(ax=ax)
 plt.show()
 ```
 
-![](README_files/figure-commonmark/cell-2-output-1.png)
+![](img/plot.png)
 
 # Benchmarks
 
-**fasterize** is fast and so is **rusterize**! Let’s try it on small and large
-datasets.
+**rusterize** is fast! Let’s try it on small and large datasets.
 
 ``` python
 from rusterize.core import rusterize
@@ -167,7 +176,7 @@ Then you can run it with [pytest](https://docs.pytest.org/en/stable/)
 and
 [pytest-benchmark](https://pytest-benchmark.readthedocs.io/en/stable/):
 
-``` {shell}
+```
 pytest <python file> --benchmark-min-rounds=20 --benchmark-time-unit='s'
 
 --------------------------------------------- benchmark: 1 tests --------------------------------------------
@@ -180,7 +189,7 @@ test_small            0.5083   0.6416   0.5265  0.0393   0.5120  0.0108       2;
 
 And fasterize:
 
-``` {r}
+``` r
 large <- st_read("Mammals_Terrestrial/Mammals_Terrestrial.shp", quiet = TRUE)
 small <- large[1:1000, ]
 fn <- function(v) {
@@ -195,7 +204,7 @@ microbenchmark(
 )
 ```
 
-``` {shell}
+```
 Unit: seconds
       expr             min        lq      mean    median        uq       max  neval
  fasterize_large  9.565781  9.815375  10.02838  9.984965  10.18532  10.66656     20
@@ -207,7 +216,7 @@ And on even
 datasets? This is a benchmark with 350K+ geometries rasterized at 30
 meters (20 rounds) with no field value and pixel function `sum`.
 
-``` {shell}
+```
 # rusterize
 --------------------------------------------- benchmark: 1 tests --------------------------------------------
 Name (time in s)         Min      Max     Mean  StdDev   Median     IQR  Outliers     OPS  Rounds  Iterations
@@ -223,7 +232,7 @@ Unit: seconds
 
 # Comparison with other tools
 
-While `rusterize` is fast, there are other very fast solutions out there, including
+While `rusterize` is fast, there are other very fast solutions out there, including:
 - `GDAL`
 - `rasterio`
 - `geocube`

rusterize-0.1.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+rusterize-0.1.1.dist-info/METADATA,sha256=82TdiZEs_ruMJ_uAl_Spc_yKByUCVbK6f8BWSEJPMgU,8570
+rusterize-0.1.1.dist-info/WHEEL,sha256=wK_6Lwbu_tU_K4QRNYNiwYBiniUr5XZyljMKmHIWzV0,130
+rusterize-0.1.1.dist-info/licenses/LICENSE,sha256=v-2DqBji_azGEWFDxBhw-CNIRu8450vBbloLx6UNqLU,1108
+rusterize/__init__.py,sha256=OymrFdgWCN3VMuSM3oXoGKeagAd-5ayPsYyXnQ_HsDE,101
+rusterize/core.py,sha256=9nsqL-v5Bw5DezS_kpnDx1eQHooJr6zK1TpWSKxJT94,4574
+rusterize/rusterize.abi3.so,sha256=OJKWbs8k7_YpJaMs0w8twI-vFW19NdNyVvuZA1P2HTU,32692304
+rusterize-0.1.1.dist-info/RECORD,,

{rusterize-0.1.0.dist-info → rusterize-0.1.1.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: maturin (1.8.1)
+Generator: maturin (1.8.2)
 Root-Is-Purelib: false
 Tag: cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64

rusterize-0.1.0.dist-info/RECORD

@@ -1,7 +0,0 @@
-rusterize-0.1.0.dist-info/METADATA,sha256=pS1UlizVrXEDCis4_jefaIP1bDrZH5lJGquhtWwM69g,7938
-rusterize-0.1.0.dist-info/WHEEL,sha256=_gzWyNiyF3zIi6bV2Xk_5Drw2QYxB-ErInzINlELJDQ,130
-rusterize-0.1.0.dist-info/licenses/LICENSE,sha256=v-2DqBji_azGEWFDxBhw-CNIRu8450vBbloLx6UNqLU,1108
-rusterize/__init__.py,sha256=OymrFdgWCN3VMuSM3oXoGKeagAd-5ayPsYyXnQ_HsDE,101
-rusterize/core.py,sha256=eSBSQMebf3vELR6FHvmL7j-66mnWcRDXiow-flG5H8M,2861
-rusterize/rusterize.abi3.so,sha256=LgguNCuiyMLQFbi7RIVIA8UDtnaZKWe5p0R11UagG6s,32645752
-rusterize-0.1.0.dist-info/RECORD,,