starsExtra (version 0.2.8)

focal2: Apply a focal filter on a raster

Description

Applies a focal filter with weighted neighborhood w on a raster. The weights (w) can be added to, subtracted from, multiplied by or divided with the raster values (as specified with weight_fun). The focal cell is then taken as the mean, sum, minimum or maximum of the weighted values (as specified with fun). Input and output are rasters of class stars, single-band (i.e., only `"x"` and `"y"` dimensions), with one attribute.

Usage

focal2(
  x,
  w,
  fun = "mean",
  weight_fun = "*",
  na.rm = FALSE,
  mask = FALSE,
  na_flag = -9999
)

Value

The filtered stars raster.

Arguments

x

A raster (class stars) with one attribute and two dimensions: x and y, i.e., a single-band raster.

w

Weights matrix defining the neighborhood size around the focal cell, as well as the weights. For example, matrix(1,3,3) implies a neighborhood of size 3*3 with equal weights of 1 for all cells. The matrix must be square, i.e., with an odd number of rows and columns.

fun

A function to aggregate the resulting values for each neighborhood. Possible values are: "mean", "sum", "min", "max", and "mode". The default is "mean", i.e., the resulting values per neighborhood are averaged before being assigned to the new focal cell value.

weight_fun

An operator which is applied on each pair of values comprising the cell value and the respective weight value, as in raster_value-weight. Possible values are: "+", "-", "*", "/". The default is "*", i.e., each cell value is multiplied by the respective weight.

na.rm

Should NA values in the neighborhood be removed from the calculation? Default is FALSE.

mask

If TRUE, pixels with NA in the input are set to NA in the output as well, i.e., the output is "masked" using the input (default is FALSE).

na_flag

Value used to mark NA values in C code. This should be set to a value which is guaranteed to be absent from the input raster x (default is -9999).

References

The function interface was inspired by function raster::focal. The C code for this function is a modified and expanded version of the C function named applyKernel included with R package spatialfil.

Examples

# Small example
data(dem)
dem_mean3 = focal2(dem, matrix(1, 3, 3), "mean")
r = c(dem, round(dem_mean3, 1), along = 3)
r = st_set_dimensions(r, 3, values = c("input", "output (mean, k=3)"))
plot(r, text_values = TRUE, breaks = "equal", col = terrain.colors(11))
# \donttest{
# Larger example
data(carmel)
carmel_mean15 = focal2(carmel, matrix(1, 15, 15), "mean")
r = c(carmel, carmel_mean15, along = 3)
r = st_set_dimensions(r, 3, values = c("input", "output (mean, k=15)"))
plot(r, breaks = "equal", col = terrain.colors(11))
# }