terra (version 1.4-22)

focal: Focal values

Description

Calculate focal ("moving window") values for the neighborhood of focal cells using a matrix of weights, perhaps in combination with a function.

Usage

# S4 method for SpatRaster
focal(x, w=3, fun="sum", ..., na.only=FALSE, 
		fillvalue=NA, expand=FALSE, filename="", overwrite=FALSE, wopt=list())

Arguments

x

SpatRaster

w

window. The window can be defined as one (for a square) or two numbers (row, col); or with an odd-sized weights matrix. See Details.

fun

function that takes multiple numbers, and returns a numeric vector (one or multiple numbers). For example mean, modal, min or max

...

additional arguments passed to fun such as na.rm

na.only

logical. Should only missing values in x be changed?

fillvalue

numeric. The value of the cells in the virtual rows and columns outside of the raster

expand

logical. If TRUE The value of the cells in the virtual rows and columns outside of the raster are set to be the same as the value on the border

filename

character. Output filename

overwrite

logical. If TRUE, filename is overwritten

wopt

additional arguments for writing files as in writeRaster

Value

SpatRaster

Details

focal

The window used must have odd dimensions. If you need even sides, you can use a matrix and add a column or row with weights of zero.

Window values are typically 0 or 1, or a value between 0 and 1 if you are using a rectangular area and/or the "sum" function. They can also be NA; these are ignored in the computation. That can be useful to compute the mean, min, or max value for a non-rectangular area.

Example weight matrices

Laplacian filter: filter=matrix(c(0,1,0,1,-4,1,0,1,0), nrow=3)

Sobel filters (for edge detection): fx=matrix(c(-1,-2,-1,0,0,0,1,2,1), nrow=3) fy=matrix(c(1,0,-1,2,0,-2,1,0,-1), nrow=3)

See Also

focalMat, focalValues

Examples

# NOT RUN {
r <- rast(ncols=10, nrows=10, ext(0, 10, 0, 10))
values(r) <- 1:ncell(r)

f <- focal(r, w=3, fun=function(x, ...) quantile(x, c(.25, .5, .75), ...), na.rm=TRUE) 

f <- focal(r, w=3, fun="mean") 

# the following two statements are equivalent:
a <- focal(r, w=matrix(1/9, nc=3, nr=3))
b <- focal(r, w=3, fun=mean, na.rm=FALSE)

# but this is different
d <- focal(r, w=3, fun=mean, na.rm=TRUE)
# }