Compute zonal statistics, that is summarized values of a Raster* object for each "zone" defined by a RasterLayer.

If `stat`

is a true `function`

, `zonal`

will fail (gracefully) for very large Raster objects, but it will in most cases work for functions that can be defined as by a character argument ('mean', 'sd', 'min', 'max', or 'sum'). In addition you can use 'count' to count the number of cells in each zone (only useful with `na.rm=TRUE`

, otherwise `freq(z)`

would be more direct.

If a function is used, it should accept a `na.rm`

argument (or at least a `...`

argument)

```
# S4 method for class 'RasterLayer,RasterLayer'
zonal(x, z, fun='mean', digits=0, na.rm=TRUE, ...)
# S4 method for class 'RasterStackBrick,RasterLayer'
zonal(x, z, fun='mean', digits=0, na.rm=TRUE, ...)
```

## Arguments

- x
Raster* object

- z
RasterLayer with codes representing zones

- fun
function to be applied to summarize the values by zone. Either as character: 'mean', 'sd', 'min', 'max', 'sum'; or, for relatively small Raster* objects, a proper function

- digits
integer. Number of digits to maintain in 'zones'. By default averaged to an integer (zero digits)

- na.rm
logical. If `TRUE`

, `NA`

values in `x`

are ignored

- ...
additional arguments. One implemented: `progress`

, as in `writeRaster`

## Value

A matrix with a value for each zone (unique value in `zones`

)

## See also

See `cellStats`

for 'global' statistics (i.e., all of `x`

is considered a single zone), and `extract`

for summarizing values for polygons

## Examples

```
r <- raster(ncols=10, nrows=10)
values(r) <- runif(ncell(r)) * 1:ncell(r)
z <- r
values(z) <- rep(1:5, each=20)
# for large files, use a character value rather than a function
zonal(r, z, 'sum')
#> zone sum
#> [1,] 1 106.8764
#> [2,] 2 332.4794
#> [3,] 3 576.8979
#> [4,] 4 831.4907
#> [5,] 5 987.6777
# for smaller files you can also provide a function
if (FALSE) { # \dontrun{
zonal(r, z, mean)
zonal(r, z, min)
} # }
# multiple layers
zonal(stack(r, r*10), z, 'sum')
#> zone layer.1 layer.2
#> [1,] 1 106.8764 1068.764
#> [2,] 2 332.4794 3324.794
#> [3,] 3 576.8979 5768.979
#> [4,] 4 831.4907 8314.907
#> [5,] 5 987.6777 9876.777
```