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
.)
# 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
)
a RasterLayer
, RasterStack
, or RasterBrick
a sf object with polygonal geometries
an optional function or character vector, as described below
additional arguments to pass to fun
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.
if TRUE
, display a progress bar during processing
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.
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.
always return a data frame instead of a vector, even if
x
has only one layer and fun
has length 1
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
.
if TRUE
, apply fun
to each layer of
x
independently. If FALSE
, apply fun
to all layers of x
simultaneously.
when fun
is not NULL
, an optional
character vector of columns from y
to be
included in returned data frame.
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 to be computed when fun == 'quantile'
a weighting raster to be used with the weighted_mean
and weighted_sum
summary operations.
a vector or list of data frames, depending on the type of x
and the
value of fun
(see 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.
# 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