exactextractr (version 0.5.1)

exact_extract: 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 Raster,sf
exact_extract(
  x,
  y,
  fun = NULL,
  ...,
  include_xy = FALSE,
  progress = TRUE,
  max_cells_in_memory = 3e+07,
  include_cell = FALSE,
  force_df = FALSE,
  full_colnames = FALSE,
  stack_apply = FALSE,
  append_cols = NULL,
  include_cols = NULL,
  quantiles = NULL
)

# S4 method for 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, force_df = FALSE, full_colnames = FALSE, stack_apply = FALSE, append_cols = NULL, include_cols = NULL, quantiles = NULL )

# S4 method for 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, force_df = FALSE, full_colnames = FALSE, stack_apply = FALSE, append_cols = NULL, include_cols = NULL, quantiles = NULL )

# S4 method for 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, force_df = FALSE, full_colnames = FALSE, stack_apply = FALSE, append_cols = NULL, include_cols = NULL, quantiles = NULL )

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, and fun is NULL, augment the returned data frame for each feature with columns for cell center coordinates (x and y). If TRUE and fun is not NULL, add x and y to the data frame passed to fun for each feature.

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, and fun is NULL, augment the returned data frame for each feature with a column for the cell index (cell). If TRUE and fun is not NULL, add cell to the data frame passed to fun for each feature.

force_df

always return a data frame instead of a vector, even if x has only one layer and fun has length 1

full_colnames

include the names of x in the names of the returned data frame, even if x has only one layer. This is useful when the results of multiple calls to exact_extract are combined with cbind.

stack_apply

if TRUE, apply fun to each layer of x independently. If FALSE, apply fun to all layers of x simultaneously.

append_cols

when fun is not NULL, an optional character vector of columns from y to be included in returned data frame.

include_cols

an optional character vector of column names in y to be added to the data frame for each feature that is either returned (when fun is NULL) or passed to fun.

quantiles

quantiles to be computed when fun == 'quantile'

weights

a weighting raster to be used with the weighted_mean and weighted_sum summary operations.

Value

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

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 force_df can be used to always return a data frame instead of a vector.) In all of the summary operations, NA values in the raster are ignored (i.e., na.rm = TRUE.)

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

  • median - the median cell value, weighted by the fraction of each cell that is covered by the polygon

  • quantile - arbitrary quantile(s) of cell values, specified in quantiles, 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.

Examples

Run this code
# NOT RUN {
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]))

# }

Run the code above in your browser using DataCamp Workspace