focal.function: Local and Focal Grid Functions

In RSAGA: SAGA Geoprocessing and Terrain Analysis

Local and Focal Grid Functions

Description

focal.function cuts out square or circular moving windows from a grid (matrix) and applies a user-defined matrix function to calculate e.g. a terrain attribute or filter the grid. The function is suitable for large grid files as it can process them row by row. local.function represents the special case of a moving window of radius 1. Users can define their own functions operating on moving windows, or use simple functions such as median to define filters.

Usage

focal.function(
  in.grid,
  in.factor.grid,
  out.grid.prefix,
  path = NULL,
  in.path = path,
  out.path = path,
  fun,
  varnames,
  radius = 0,
  is.pixel.radius = TRUE,
  na.strings = "NA",
  valid.range = c(-Inf, Inf),
  nodata.values = c(),
  out.nodata.value,
  search.mode = c("circle", "square"),
  digits = 4,
  hdr.digits = 10,
  dec = ".",
  quiet = TRUE,
  nlines = Inf,
  mw.to.vector = FALSE,
  mw.na.rm = FALSE,
  ...
)

gapply(in.grid, fun, varnames, mw.to.vector = TRUE, mw.na.rm = TRUE, ...)

local.function(...)

Arguments

in.grid	file name of input ASCII grid, relative to in.path
in.factor.grid	optional file name giving a gridded categorical variables defining zones; zone boundaries are used as breaklines for the moving window (see Details)
out.grid.prefix	character string (optional), defining a file name prefix to be used for the output file names; a dash (-) will separate the prefix and the varnames
path	path in which to look for in.grid and write output grid files; see also in.path and out.path, which overwrite path if they are specified
in.path	path in which to look for in.grid (defaults to path)
out.path	path in which to write output grid files; defaults to path
fun	a function, or name of a function, to be applied on the moving window; see Details
varnames	character vector specifying the names of the variable(s) returned by fun; if missing, focal.function will try to determine the varnames from fun itself, or from a call to fun if this is a function (see Details)
radius	numeric value specifying the (circular or square) radius of the moving window; see is.pixel.radius and search.mode; note that all data within distance <=radius will be included in the moving window, not <radius.
is.pixel.radius	logical: if TRUE (default), the radius will be interpreted as a (possibly non-integer) number of pixels; if FALSE, it is interpreted as a radius measured in the grid (map) units.
na.strings	passed on to scan()
valid.range	numeric vector of length 2, specifying minimum and maximum valid values read from input file; all values <valid.range[1] or >valid.range[1] will be converted to NA.
nodata.values	numeric vector: any values from the input grid file that should be converted to NA, in addition to the nodata value specified in the grid header
out.nodata.value	numeric: value used for storing NAs in the output file(s); if missing, use the same nodata value as specified in the header of the input grid file
search.mode	character, either "circle" (default) for a circular search window, or "square" for a squared one.
digits	numeric, specifying the number of digits to be used for output grid file.
hdr.digits	numeric, specifying the number of digits to be used for the header of the output grid file (default: 10; see write.ascii.grid.header()).
dec	character, specifying the decimal mark to be used for input and output.
quiet	If TRUE, gives some output ("*") after every 10th line of the grid file and when the job is done.
nlines	Number of lines to be processed; useful for testing purposes.
mw.to.vector	logical: Should the content of the moving window be coerced (from a matrix) to a vector?
mw.na.rm	logical: Should NAs be removed from moving window prior to passing the data to fun? Only applicable when mw.to.vector=TRUE.
...	Arguments to be passed to fun; local.function: arguments to be passed to focal.function.

Details

focal.function passes a square matrix of size 2*radius+1 to the function fun if mw.to.vector=FALSE (default), or a vector of length <=(2*radius+1)^2 if mw.to.vector=TRUE. This matrix or vector will contain the content of the moving window, which may possibly contain NAs even if the in.grid has no nodata values, e.g. due to edge effects. If search.mode="circle", values more than radius units (pixels or grid units, depending on is.pixel.radius) away from the center pixel / matrix entry will be set to NA. In addition, valid.range, nodata.values, and the nodata values specified in the in.grid are checked to assign further NAs to pixels in the moving window. Finally, if in.factor.grid specifies zones, all pixels in the moving window that belong to a different zone than the center pixel are set to NA, or, in other words, zone boundaries are used as breaklines.

The function fun should return a single numeric value or a numeric vector. As an example, the function resid.minmedmax() returns the minimum, median and maximum of the difference between the values in the moving window and the value in the center grid cell. In addition to the (first) argument receiving the moving window data, fun may have additional arguments; the ... argument of focal.function is passed on to fun. resid.quantile() is a function that uses this feature.

Optionally, fun should support the following feature: If no argument is passed to it, then it should return a character vector giving variable names to be used for naming the output grids. The call resid.minmedmax(), for example, returns c("rmin","rmed","rmax"); this vector must have the same length as the numeric vector returned when moving window data is passed to the function. This feature is only used if no varnames argument is provided. Note that the result is currently being abbreviate()d to a length of 6 characters.

Input and output file names are built according to the following schemes:

Input: [<in.path>/]<in.grid>

Zones: [<in.path>/]<in.factor.grid> (if specified)

Output: [<out.path>/][<out.grid.prefix>-]<varnames>.asc

For the input files, .asc is used as the default file extension, if it is not specified by the user.

Value

focal.function and local.function return the character vector of output file names.

Note

These functions are not very efficient ways of calculating e.g. (focal) terrain attributes compared to for example the SAGA modules, but the idea is that you can easily specify your own functions without starting to mess around with C code. For example try implementing a median filter as a SAGA module... or just use the code shown in the example!

Author(s)

Alexander Brenning

References

Brenning, A. (2008): Statistical geocomputing combining R and SAGA: The example of landslide susceptibility analysis with generalized additive models. In: J. Boehner, T. Blaschke, L. Montanarella (eds.), SAGA - Seconds Out (= Hamburger Beitraege zur Physischen Geographie und Landschaftsoekologie, 19), 23-32.

See Also

multi.focal.function(), multi.local.function(), resid.median(), resid.minmedmax(), relative.position(), resid.quantile(), resid.quartiles(), relative.rank(), wind.shelter(), create.variable.name()

Examples

## Not run: 
# A simple median filter applied to dem.asc:
gapply("dem","median",radius=3)
# Same:
#focal.function("dem",fun="median",radius=3,mw.to.vector=TRUE,mw.na.rm=TRUE)
# See how the filter has changed the elevation data:
d1 = as.vector(read.ascii.grid("dem")$data)
d2 = as.vector(read.ascii.grid("median")$data)
hist(d1-d2,br=50)

## End(Not run)
# Wind shelter index used by Plattner et al. (2004):
## Not run: 
ctrl = wind.shelter.prep(6,-pi/4,pi/12,10)
focal.function("dem",fun=wind.shelter,control=ctrl,
    radius=6,search.mode="circle")

## End(Not run)
# Or how about this, if "aspect" is local terrain exposure:
## Not run: 
gapply("aspect","cos") # how "northerly-exposed" is a pixel?
gapply("aspect","sin") # how "easterly-exposed" is a pixel?
# Same result, but faster:
focal.function("aspect",fun=function(x) c(cos(x),sin(x)), varnames=c("cos","sin"))

## End(Not run)

RSAGA documentation built on Dec. 10, 2022, 1:12 a.m.