exactextractr R Package

To perform calculations like population-weighted temperature or area-weighted precipitation, use the weights argument in exact_extract.

Requirements for the weighting raster:

1. Must use the same coordinate system as the primary raster.
2. Must use a compatible grid (the higher resolution grid's cell boundaries must coincide with the lower resolution grid's boundaries).

Using named weighted operations:

# Area-weighted mean precipitation
brazil$mean_dec_prec_weighted <- exact_extract(prec[[12]], brazil, 'weighted_mean', weights = area(prec))

Using custom functions with weights: When using a custom function with a weighting raster, the function signature must be function(values, coverage_frac, weights).

# Area-weighted mean using a custom function
brazil$mean_dec_prec_weighted <- 
  exact_extract(prec[[12]], brazil, function(values, coverage_frac, weights) {
    weighted.mean(values, coverage_frac * weights)
  }, weights = area(prec))

If built-in operations are insufficient, you can pass an arbitrary R function to the fun parameter. Because exactextractr accounts for partial cell coverage, your custom function must accept two arguments: values (the raster values) and coverage_fraction (the fraction of the cell area covered by the polygon).

If you also provide a weights argument, your custom function must accept a third argument: weights.

Examples:

# Number of cells covered by the polygon (ignoring raster values)
exact_extract(rast, poly, function(values, coverage_fraction) sum(coverage_fraction))

# Sum of values weighted by coverage fraction
exact_extract(rast, poly, function(values, coverage_fraction) sum(values * coverage_fraction, na.rm=TRUE))

# Number of distinct values in cells more than 10% covered
exact_extract(rast, poly, function(values, coverage_fraction) length(unique(values[coverage_fraction > 0.1])))

# Number of cells covered by the polygon (raster values are ignored)
exact_extract(rast, poly, function(values, coverage_fraction)
                            sum(coverage_fraction))

# Sum of defined raster values within the polygon, accounting for coverage fraction
exact_extract(rast, poly, function(values, coverage_fraction)
                            sum(values * coverage_fraction, na.rm=TRUE))

# Number of distinct raster values within the polygon (coverage fractions are ignored)
exact_extract(rast, poly, function(values, coverage_fraction)
                            length(unique(values)))

# Number of distinct raster values in cells more than 10% covered by the polygon
exact_extract(rast, poly, function(values, coverage_fraction)
                            length(unique(values[coverage_fraction > 0.1])))

You can implement complex logic involving multiple layers (e.g., calculating average temperature from both tmin and tmax layers) by passing a RasterStack to exact_extract.

Key Behaviors:

• If stack_apply = TRUE: The summary function is applied to each layer independently.
• If stack_apply = FALSE (default): The values from all layers in the stack are provided to the summary function as a data frame.

Example: Calculating average temperature from min/max stack:

# temp is a RasterStack of tmin and tmax
brazil$tavg_dec <- exact_extract(temp, brazil,
  function(values, coverage_fraction, weights) {
    tavg <- 0.5*(values$tmin12 + values$tmax12)
    weighted.mean(tavg, coverage_fraction * weights)
  }, weights = area(prec))

tmin <- getData('worldclim', var = 'tmin', res = 10)
tmax <- getData('worldclim', var = 'tmax', res = 10)

temp <- stack(tmin[[12]], tmax[[12]])

brazil$tavg_dec <- exact_extract(temp, brazil,
  function(values, coverage_fraction, weights) {
    tavg <- 0.5*(values$tmin12 + values$tmax12)
    weighted.mean(tavg, coverage_fraction * weights)
  }, weights = area(prec))

You can pass a character vector to the fun parameter of exact_extract to use optimized, built-in summary operations. These are generally faster and more memory-efficient than passing an R function.

Standard Operations:

• count: Sum of all cell coverage fractions.
• majority (or mode): The raster value with the largest sum of coverage fractions.
• max: Maximum value of cells that intersect the polygon (ignores coverage fractions).
• mean: Mean value of cells weighted by coverage fraction.
• median: Median value of cells weighted by coverage fraction.
• quantile: Arbitrary quantile value of cells weighted by coverage fraction.
• min: Minimum value of cells that intersect the polygon (ignores coverage fractions).
• minority: The raster value with the smallest sum of coverage fractions.
• sum: Sum of values weighted by coverage fraction.
• variety: Number of distinct raster values in cells wholly or partially covered.
• variance: Population variance weighted by coverage fraction.
• stdev: Population standard deviation weighted by coverage fraction.
• coefficient_of_variation: Population coefficient of variation weighted by coverage fraction.
• frac: Fraction of covered cells occupied by each distinct raster value.

Weighted Operations (requires weights argument):

• weighted_mean: Mean of non-NA cells, weighted by (coverage fraction * weight raster value).
• weighted_sum: Sum of non-NA values, weighted by (coverage fraction * weight raster value).
• weighted_variance: Population variance of non-NA values, weighted by (coverage fraction * weight raster value).
• weighted_stdev: Population standard deviation of non-NA values, weighted by (coverage fraction * weight raster value).
• weighted_frac: Fraction of covered cells occupied by each distinct value, with coverage fractions multiplied by the weight raster value.

The S4RasterSource class is used to interface with R S4 raster objects (such as those from the raster or terra packages) within the exactextractr C++ backend. It allows the engine to read raster values from an R-managed object by mapping the raster's extent and resolution to an internal grid.

There are two ways to initialize this source:

1. From an R SEXP: Pass the R object directly. The class will attempt to derive the grid from the object.
2. With explicit extent and resolution: Pass the R object along with explicit extent and resolution vectors to define the grid manually.

You can also specify a default_value (defaults to NaN) to replace any NaN values found in the raster during reading.

// Example conceptual usage of S4RasterSource initialization
// 1. Using the R object directly
S4RasterSource source(rast_object, default_val);

// 2. Using explicit extent and resolution
S4RasterSource source(rast_object, extent_vector, res_vector, default_val);