R: Extract or summarize values from Raster* objects

exact_extract {exactextractr} | R Documentation

## Extract or summarize values from Raster* objects

### Description

Extracts the values of cells in a Raster* that are covered by a simple feature collection containing polygonal geometries, as well as the fraction of each cell that is covered by the polygon. Returns either the result of a summary operation or function applied to the values and coverage fractions (if `fun` is specified), or a data frame containing the values and coverage fractions themselves (if `fun` is `NULL`.)

### Usage

    ## S4 method for signature 'Raster,sf'
    exact_extract(
      x,
      y,
      fun = NULL,
      ...,
      include_xy = FALSE,
      progress = TRUE,
      max_cells_in_memory = 3e+07,
      include_cell = FALSE
    )

    ## S4 method for signature 'Raster,sfc_MULTIPOLYGON'
    exact_extract(
      x,
      y,
      fun = NULL,
      ...,
      weights = NULL,
      include_xy = FALSE,
      progress = TRUE,
      max_cells_in_memory = 3e+07,
      include_cell = FALSE
    )

    ## S4 method for signature 'Raster,sfc_POLYGON'
    exact_extract(
      x,
      y,
      fun = NULL,
      ...,
      weights = NULL,
      include_xy = FALSE,
      progress = TRUE,
      max_cells_in_memory = 3e+07,
      include_cell = FALSE
    )

    ## S4 method for signature 'Raster,sfc_GEOMETRY'
    exact_extract(
      x,
      y,
      fun = NULL,
      ...,
      weights = NULL,
      include_xy = FALSE,
      progress = TRUE,
      max_cells_in_memory = 3e+07,
      include_cell = FALSE
    )

### Arguments

`x` | a `RasterLayer`, `RasterStack`, or `RasterBrick`
`y` | a sf object with polygonal geometries
`fun` | an optional function or character vector, as described below
`...` | additional arguments to pass to `fun`
`include_xy` | if `TRUE`, augment the returned data frame with columns for cell center coordinates (`x` and `y`) or pass them to `fun`
`progress` | if `TRUE`, display a progress bar during processing
`max_cells_in_memory` | the maximum number of raster cells to load at a given time when using a named summary operation for `fun` (as opposed to a function defined using R code). If a polygon covers more than `max_cells_in_memory` raster cells, it will be processed in multiple chunks.
`include_cell` | if `TRUE`, augment the returned data frame with column for cell index
`weights` | a weighting raster to be used with the `weighted_mean` and `weighted_sum` summary operations.

### Details

The value of `fun` may be set to a string (or vector of strings) representing summary operations supported by the exactextract library. If the input raster has a single layer and a single summary operation is specified, `exact_extract` will return a vector with the result of the summary operation for each feature in the input. If the input raster has multiple layers, or if multiple summary operations are specified, `exact_extract` will return a data frame with a row for each feature and a column for each summary operation / layer combination.

The following summary operations are supported:

- `min` - the minimum defined value in any raster cell wholly or partially covered by the polygon

- `max` - the maximum defined value in any raster cell wholly or partially covered by the polygon

- `count` - the sum of fractions of raster cells with defined values covered by the polygon

- `sum` - the sum of defined raster cell values, multiplied by the fraction of the cell that is covered by the polygon

- `mean` - the mean cell value, weighted by the fraction of each cell that is covered by the polygon

- `mode` - the most common cell value, weighted by the fraction of each cell that is covered by the polygon. Where multiple values occupy the same maximum number of weighted cells, the largest value will be returned.

- `majority` - synonym for `mode`

- `minority` - the least common cell value, weighted by the fraction of each cell that is covered by the polygon. Where multiple values occupy the same minimum number of weighted cells, the smallest value will be returned.

- `variety` - the number of distinct values in cells that are wholly or partially covered by the polygon.

- `variance` - the population variance of cell values, weighted by the fraction of each cell that is covered by the polygon.

- `stdev` - the population standard deviation of cell values, weighted by the fraction of each cell that is covered by the polygon.

- `coefficient_of_variation` - the population coefficient of variation of cell values, weighted by the fraction of each cell that is covered by the polygon.

- `weighted_mean` - the mean cell value, weighted by the product of the fraction of each cell covered by the polygon and the value of a second weighting raster provided as `weights`

- `weighted_sum` - the sum of defined raster cell values, multiplied by the fraction of each cell that is covered by the polygon and the value of a second weighting raster provided as `weights`

Alternatively, an R function may be provided as `fun`. The function will be called for each feature with with vectors of cell values and weights as arguments. `exact_extract` will then return a vector of the return values of `fun`.

If `fun` is not specified, `exact_extract` will return a list with one data frame for each feature in the input feature collection. The data frame will contain a column with values from each layer in the input 'Raster*', and a final column indicating the fraction of the cell that is covered by the polygon.

### Value

a vector or list of data frames, depending on the type of `x` and the value of `fun` (see Details)

### Examples

    rast <- raster::raster(matrix(1:100, ncol=10), xmn=0, ymn=0, xmx=10, ymx=10)
    poly <- sf::st_as_sfc('POLYGON ((2 2, 7 6, 4 9, 2 2))')

    # named summary operation on RasterLayer, returns vector
    exact_extract(rast, poly, 'mean')

    # two named summary operations on RasterLayer, returns data frame
    exact_extract(rast, poly, c('min', 'max'))

    # named summary operation on RasterStack, returns data frame
    stk <- raster::stack(list(a=rast, b=sqrt(rast)))
    exact_extract(stk, poly, 'mean')

    # named weighted summary operation, returns vector
    weights <- raster::raster(matrix(runif(100), ncol=10), xmn=0, ymn=0, xmx=10, ymx=10)
    exact_extract(rast, poly, 'weighted_mean', weights=weights)

    # custom summary function, returns vector
    exact_extract(rast, poly, function(value, cov_frac) length(value[cov_frac > 0.9]))

[Package exactextractr version 0.4.0 Index]