compute_zonal_stats_per_category

eolab.georastertools.processing.stats.compute_zonal_stats_per_category(geoms: GeoDataFrame, image: str, bands: List[int] = [1], stats: List[str] = ['min', 'max', 'mean', 'std'], categories: GeoDataFrame | None = None, category_index: str = 'Classe', category_labels: Dict[str, str] | None = None)[source]

Compute zonal statistics for an input raster image, categorized by specified subregions.

This function calculates statistical metrics for a raster image over a set of geometries (e.g., polygons) provided in geoms. If a set of categories (subregions within each geometry) is provided, statistics are computed separately for each category within each geometry.

Parameters:

  • geoms (GeoDataFrame) – A GeoDataFrame containing the input geometries (e.g., polygons) to compute statistics over.

  • image (str) – The file path to the input raster image.

  • bands (List[int], optional) – A list of raster band indices to process. Defaults to [1] (the first band).

  • stats (List[str], optional) – A list of statistical metrics to compute. Supported values include: - “min”: Minimum value within the geometry. - “max”: Maximum value within the geometry. - “mean”: Mean value within the geometry. - “std”: Standard deviation within the geometry. Defaults to [“min”, “max”, “mean”, “std”].

  • categories (GeoDataFrame, optional) – A GeoDataFrame containing category geometries that define subregions of the input geometries. Defaults to None.

  • category_index (str, optional) – The column in the categories GeoDataFrame that identifies category labels for each geometry. Defaults to ‘Classe’.

  • category_labels (Dict[str, str], optional) – A dictionary mapping category values (from category_index) to human-readable labels. If provided, these labels replace category values in the output. Defaults to None.

Returns:

A nested list of dictionaries containing the computed statistics: - Outer list corresponds to each input geometry in geoms. - Inner list corresponds to each raster band being processed. - Each dictionary maps statistic names (e.g., “mean”, “max”) to their respective values.

Return type:

List[List[Dict[str, float]]]

Raises:

IOError – If any input geometry is not of type Polygon or MultiPolygon.

Notes

  • For each geometry in geoms, the function subdivides it into subregions based on the geometries in categories (if provided). Statistics are then computed for each subregion separately.

  • The function assumes that the raster image is georeferenced and aligned with the coordinate system of the input geometries.

Example

``` import geopandas as gpd from georastertools import compute_zonal_stats_per_category

geoms = gpd.read_file(“regions.shp”) categories = gpd.read_file(“landcover.shp”) image_path = “satellite_image.tif”

stats = compute_zonal_stats_per_category(

geoms=geoms, image=image_path, categories=categories, category_index=”Land_Type”, category_labels={1: “Forest”, 2: “Urban”, 3: “Water”}

)

for geometry_stats in stats:

print(geometry_stats)

```