raster (version 1.9-27)

focal: Focal values

Description

Calculate "moving window" values for the neighborhood of focal cells using a matrix of weights, perhaps in combination with a function. This function replaces focal_old, focalNA and focalFilter

Usage

focal(x, w, fun, filename='', na.rm=FALSE, pad=FALSE, padValue=NA, NAonly=FALSE, ...)

Arguments

x

RasterLayer

w

matrix of weights (the moving window), e.g. a 3 by 3 matrix; see Details. The matrix can also be expressed as the number of cells in a single direction or in two directions from the focal cell, in which case the weights are all set to 1. I.e. w=3

fun

function (optional). The function fun should take multiple numbers, and return a single number. For example mean, modal, min or max. It should also accept a na.rm argument (or ignore it, e.g. as one of the 'dots' arguments. For example, length

filename

character. Filename for a new raster (optional)

na.rm

logical. If TRUE, NA will be removed from focal computations. The result will only be NA if all focal cells are NA. Except for some special cases (weights of 1, mean function), using na.rm=TRUE is genera

pad

logical. If TRUE, additional 'virtual' rows and columns are padded to x such that there are no edge effects. This can be useful when a function needs to have access to the central cell of the filter

padValue

logical. The value of the cells of the padded rows and columns

NAonly

logical. If TRUE, only cell values that are NA are replaced with the computed focal values

...

additional arguments. See Details.

Value

• RasterLayer

Details

focal uses a matrix of weights for the neighborhood of the focal cells. The default function is sum. It is computationally much more efficient to adjust the weights-matrix than to use another function through the fun argument. Thus while the following two statements are equivalent, the first one is faster than the second one: a <- focal2(x, w=matrix(1/9, nc=3, nc=3)) b <- focal2(x, w=3, fun=mean) Gaussian filter: filter=matrix(c(1,2,3,2,1,2,3,4,3,2,3,4,5,4,3,2,3,4,3,2,1,2,3,2,1), nrow=5)/65 Laplacian filter: filter=matrix(c(0,1,0,1,-4,1,0,1,0), nrow=3) Sobel filter: filter=matrix(c(1,2,1,0,0,0,-1,-2,-1) / 4, nrow=3) The following additional arguments can be passed, to replace default values for this function rll{ overwrite Logical. If TRUE, "filename" will be overwritten if it exists format Character. Output file type. See writeRaster datatype Character. Output data type. See dataType progress Character. "text", "window", or "" (the default, no progress bar) }

Examples

r <- raster(ncols=36, nrows=18)
r[] <- runif(ncell(r)) 

# 3x3 mean filter
r3 <- focal(r, w=matrix(1/9,nrow=3,ncol=3)) 

# 5x5 mean filter
r5 <- focal(r, w=matrix(1/25,nrow=5,ncol=5)) 

# Gaussian filter
gf=matrix(c(1,2,3,2,1,2,3,4,3,2,3,4,5,4,3,2,3,4,3,2,1,2,3,2,1), nrow=5)/65
rg <- focal(r, w=gf)

# The max value for the lower-rigth corner of a 3x3 matrix around a focal cell
f = matrix(c(0,0,0,0,1,1,0,1,1), nrow=3)
f
rm <- focal(r, w=f, fun=max)