RS_ZonalStats¶

Computes a single summary statistic of the raster pixels covered by a region of interest geometry.

Usage¶

double RS_ZonalStats(rast: raster, roi: geometry, stat_type: string)
double RS_ZonalStats(rast: raster, roi: geometry, band: integer, stat_type: string)
double RS_ZonalStats(rast: raster, roi: geometry, band: integer, stat_type: string, all_touched: boolean)
double RS_ZonalStats(rast: raster, roi: geometry, band: integer, stat_type: string, all_touched: boolean, exclude_no_data: boolean)
double RS_ZonalStats(rast: raster, roi: geometry, band: integer, stat_type: string, all_touched: boolean, exclude_no_data: boolean, lenient: boolean)

Arguments¶

rast (raster): Input raster
roi (geometry)
band (integer)
stat_type (string)
all_touched (boolean)
exclude_no_data (boolean)
lenient (boolean): If true (the default), return NULL when the roi does not intersect the raster; if false, raise an error.

[!WARNING]

Experimental. This function is experimental; its behavior may change without notice.

Description¶

RS_ZonalStats returns one summary statistic of the pixels of a single band that a region of interest (ROI) geometry covers. A pixel is included when its center falls inside the roi (or, with all_touched, when the roi touches it at all). By default the band’s nodata pixels are excluded.

The statistic is one of count, sum, mean, median, mode, stddev, variance, min, or max. count is returned as a whole number; all other statistics are floating point. Variance and standard deviation are the sample (n-1) values, and mode breaks ties toward the larger value.

When the ROI overlaps the raster but selects no pixel, count is 0 and every other statistic is NULL. When the ROI does not intersect the raster at all, the result is NULL under the default lenient behavior, or an error when lenient is set to false.

The band, all_touched, exclude_no_data, and lenient arguments are added one at a time by the wider overloads; all_touched defaults to false, exclude_no_data to true, and lenient to true. The band-less overload does not default to band 1 on a multiband raster: naming the band is required there. This function operates on 2-D (y, x) bands; computing a statistic per non-spatial plane of an N-D band is not supported.

Use RS_ZonalStatsAll to compute every statistic at once.

Examples¶

SELECT RS_ZonalStats(
  RS_Example(),
  ST_GeomFromText('POLYGON ((60 90, 160 90, 160 190, 60 190, 60 90))', 'OGC:CRS84'),
  1,
  'mean'
);

┌──────────────────────────────────────────────────────────────────────────────┐
│ rs_zonalstats(rs_example(),st_geomfromtext(Utf8("POLYGON ((60 90, 160 90, 16 │
│      0 190, 60 190, 60 90))"),Utf8("OGC:CRS84")),Int64(1),Utf8("mean"))…     │
╞══════════════════════════════════════════════════════════════════════════════╡
│                                                                          1.0 │
└──────────────────────────────────────────────────────────────────────────────┘

SELECT RS_ZonalStats(
  RS_Example(),
  ST_GeomFromText('POLYGON ((60 90, 160 90, 160 190, 60 190, 60 90))', 'OGC:CRS84'),
  1,
  'count',
  false,
  false
);

┌──────────────────────────────────────────────────────────────────────────────┐
│ rs_zonalstats(rs_example(),st_geomfromtext(Utf8("POLYGON ((60 90, 160 90, 16 │
│ 0 190, 60 190, 60 90))"),Utf8("OGC:CRS84")),Int64(1),Utf8("count"),Boolean(… │
╞══════════════════════════════════════════════════════════════════════════════╡
│                                                                       1542.0 │
└──────────────────────────────────────────────────────────────────────────────┘