Zonal Statistics#

This module supports you in computing statistics over spatial zones. A typical application would be to compute mean areal precipitation for a catchment by using precipitation estimates from a radar grid in polar coordinates or from precipitation estimates in a Cartesian grid.

The general usage is similar to the wradlib.ipol and wradlib.adjust:

You have to create an instance of a class (derived from ZonalDataBase) by using the spatial information of your source and target objects (e.g. radar bins and catchment polygons). The Zonal Data within this object can be saved e.g. as an ESRI Shapefile.

This object is then called with another class to compute zonal statistics for your target objects by calling the class instance with an array of values (one for each source object).

Typically, creating the instance of the ZonalData class will be computationally expensive, but only has to be done once (as long as the geometries do not change).

Calling the objects with actual data, however, will be very fast.

Note

Right now we only support a limited set of 2-dimensional zonal statistics. In the future, we plan to extend this to three dimensions.

ZonalDataBase

Base class for managing 2-dimensional zonal data.

ZonalDataPoint

ZonalData object for source points

ZonalDataPoly

ZonalData object for source polygons

ZonalStatsBase

Base class for all 2-dimensional zonal statistics.

ZonalStatsPoly

Compute weighted average for target polygons based on areal weights.

ZonalStatsPoint

Compute zonal average from all points in or close to the target polygon.

mask_from_bbox

Return 2-d index array based on spatial selection from a bounding box.

get_bbox

Return bbox dictionary that represents the extent of the points.

grid_centers_to_vertices

Produces array of vertices from grid's center point coordinates.

get_clip_mask

Returns boolean mask of points coords inside polygon clippoly

class wradlib.zonalstats.ZonalDataBase(src, *, trg=None, buf=0.0, crs=None, **kwargs)[source]#

Bases: object

Base class for managing 2-dimensional zonal data.

For target polygons from either source points or source polygons. Provides the basic design for all other classes.

If no source points or polygons can be associated to a target polygon (e.g. no intersection), the created destination layer will be empty.

Data Model is built upon OGR Implementation of ESRI Shapefile

  • one src DataSource (named ‘src’) holding source polygons or points

  • one trg DataSource (named ‘trg’) holding target polygons

  • one dst DataSource (named ‘dst’) holding intersection polygons/points related to target polygons with attached index and weights fields

By using OGR there are no restrictions for the used source grids.

Warning

Writing shapefiles with the wrong locale settings can have impact on the type of the decimal. If problem arise use LC_NUMERIC=C in your environment.

Parameters
  • src (sequence or str) – sequence of source points (shape Nx2) or polygons (shape NxMx2) or ESRI Shapefile filename containing source points/polygons or DataSource object

  • trg (sequence or str) – sequence of target polygons (shape Nx2, num vertices x 2) or ESRI Shapefile filename containing target polygons or DataSource object

Keyword Arguments
  • buf (float) – (same unit as coordinates) Points/Polygons will be considered inside the target if they are contained in the buffer.

  • crs (osgeo.osr.SpatialReference) – OGR.SpatialReference will be used for DataSource object. src and trg data have to be in the same crs-format

  • silent (bool) – If True no ProgressBar is shown. Defaults to False.

Examples

See ZonalData.

property count_intersections#

Returns number of intersections

property crs#

Returns SpatialReferenceSystem object

property isecs#

Returns intersections

Returns

array (numpy.ndarray) – Array of Nx2 point coordinate arrays

get_isec(idx)[source]#

Returns intersections

Parameters

idx (int) – index of target polygon

Returns

array (numpy.ndarray) – Array of Nx2 point coordinate arrays

get_source_index(idx)[source]#

Returns source indices referring to target polygon idx

Parameters

idx (int) – index of target polygon

Returns

array (numpy.ndarray) – indices

dump_vector(filename, *, driver='ESRI Shapefile', remove=True)[source]#

Output source/target grid points/polygons to ESRI_Shapefile

target layer features are attributed with source index and weight

Parameters
  • filename (str) – path to shape-filename

  • driver (str) – OGR Vector Driver String, defaults to ‘ESRI Shapefile’

  • remove (bool) – if True, existing file will be removed before creation

load_vector(filename)[source]#

Load source/target grid points/polygons into in-memory Shapefile

Parameters

filename (str) – path to vector file

class wradlib.zonalstats.ZonalDataPoint(src, *, trg=None, buf=0.0, crs=None, **kwargs)[source]#

Bases: ZonalDataBase

ZonalData object for source points

Parameters
  • src (sequence or str) – sequence of source points (shape Nx2) or ESRI Shapefile filename containing source points

  • trg (sequence or str) – sequence of target polygons (shape Nx2, num vertices x 2) or ESRI Shapefile filename containing target polygons

Keyword Arguments
  • buf (float) – (same unit as coordinates) Points will be considered inside the target if they are contained in the buffer.

  • crs (osgeo.osr.SpatialReference) – OGR.SpatialReference will be used for DataSource object. src and trg data have to be in the same crs-format

Examples

See ZonalData.

class wradlib.zonalstats.ZonalDataPoly(src, *, trg=None, buf=0.0, crs=None, **kwargs)[source]#

Bases: ZonalDataBase

ZonalData object for source polygons

Parameters
  • src (sequence or str) – sequence of source polygons (shape NxMx2) or ESRI Shapefile filename containing source polygons

  • trg (sequence or str) – sequence of target polygons (shape Nx2, num vertices x 2) or ESRI Shapefile filename containing target polygons

Keyword Arguments
  • buf (float) – (same unit as coordinates) Polygons will be considered inside the target if they are contained in the buffer.

  • crs (osgeo.osr.SpatialReference) – OGR.SpatialReference will be used for DataSource object. src and trg data have to be in the same crs-format

Examples

See ZonalData.

class wradlib.zonalstats.ZonalStatsBase(src=None, ix=None, w=None)[source]#

Bases: object

Base class for all 2-dimensional zonal statistics.

The base class for computing 2-dimensional zonal statistics for target polygons from source points or polygons as built up with ZonalDataBase and derived classes. Provides the basic design for all other classes.

If no source points or polygons can be associated to a target polygon (e.g. no intersection), the zonal statistic for that target will be NaN.

Parameters

src (wradlib.zonalstats.ZonalDataPoly or str) – ZonalDataPoly object or filename pointing to ZonalDataPoly ESRI shapefile containing necessary ZonalData. ZonalData is available as zdata-property inside class instance.

Examples

See ZonalStats.

property zdata#
property ix#
property w#
check_empty()[source]#
mean(vals)[source]#

Evaluate (weighted) zonal mean for values given at the source points.

Parameters

vals (numpy.ndarray) – 1-d array of type float with the same length as self.src Values at the source element for which to compute zonal statistics

var(vals)[source]#

Evaluate (weighted) zonal variance for values given at the source points.

Parameters

vals (numpy.ndarray) – 1-d array of type float with the same length as self.src Values at the source element for which to compute zonal statistics

class wradlib.zonalstats.ZonalStatsPoly(src=None, **kwargs)[source]#

Bases: ZonalStatsBase

Compute weighted average for target polygons based on areal weights.

Parameters

src (ZonalDataPoly or str) – ZonalDataPoly object or filename pointing to ZonalDataPoly ESRI shapefile containing necessary Zonal Data

Examples

See ZonalStats

class wradlib.zonalstats.ZonalStatsPoint(src, **kwargs)[source]#

Bases: ZonalStatsBase

Compute zonal average from all points in or close to the target polygon.

Parameters

src (ZonalDataPoint or str) – ZonalDataPoint object or filename pointing to ZonalDataPoly ESRI shapefile containing necessary Zonal Data

Examples

See ZonalStats

wradlib.zonalstats.mask_from_bbox(x, y, bbox, *, polar=False)[source]#

Return 2-d index array based on spatial selection from a bounding box.

Use this function to create a 2-d boolean mask from 2-d arrays of grids points.

Parameters
  • x (numpy.ndarray) – x (Cartesian) coordinates of shape (num rows, num columns)

  • y (numpy.ndarray) – y (Cartesian) coordinates of shape (num rows, num columns)

  • bbox (dict) – dictionary with keys “left”, “right”, “bottom”, “top” These must refer to the same Cartesian reference system as x and y

  • polar (bool) – if True, x, y are aligned polar (azimuth x range)

Returns

mask, shape (numpy.ndarray, tuple) – mask is a boolean array that is True if the point is inside the bbox, shape is the shape of the True subgrid

wradlib.zonalstats.get_bbox(x, y)[source]#

Return bbox dictionary that represents the extent of the points.

Parameters
wradlib.zonalstats.grid_centers_to_vertices(x, y, dx, dy)[source]#

Produces array of vertices from grid’s center point coordinates.

Warning

This has to be done in the “native” grid projection. Once you reprojected the coordinates, this trivial function cannot be used to compute vertices from center points.

Parameters
  • x (numpy.ndarray) – 2-d array of x coordinates (same shape as the actual 2-D grid)

  • y (numpy.ndarray) – 2-d array of y coordinates (same shape as the actual 2-D grid)

  • dx (float) – grid spacing in x direction

  • dy (float) – grid spacing in y direction

Returns

out (numpy.ndarray) – 3-d array of vertices for each grid cell of shape (n grid points,5, 2)

wradlib.zonalstats.get_clip_mask(coords, clippoly, *, crs=None)[source]#

Returns boolean mask of points coords inside polygon clippoly

Parameters
Returns

src_mask (numpy.ndarray) – boolean array of shape coords.shape[0:-1]