multi.focal.function: Local and Focal Grid Function with Multiple Grids as Inputs

In RSAGA: SAGA Geoprocessing and Terrain Analysis

Local and Focal Grid Function with Multiple Grids as Inputs

Description

multi.focal.function cuts out square or circular moving windows from a stack of grids (matrices) and applies a user-defined matrix function that takes multiple arguments to this data. multi.local.function is a more efficiently coded special case of moving windows of size 0, i.e. functions applied to individual grid cells of a stack of grids. This is especially useful for applying predict methods of statistical models to a stack of grids containing the explanatory variables (see Examples and grid.predict()). The function is suitable for large grid files as it can process them row by row; but it may be slow because one call to the focal function is generated for each grid cell.

Usage

multi.focal.function(
  in.grids,
  in.grid.prefix,
  in.factor.grid,
  out.grid.prefix,
  path = NULL,
  in.path = path,
  out.path = path,
  fun,
  in.varnames,
  out.varnames,
  radius = 0,
  is.pixel.radius = TRUE,
  na.strings = "NA",
  valid.ranges,
  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,
  pass.location = FALSE,
  ...
)

multi.local.function(
  in.grids,
  in.grid.prefix,
  out.grid.prefix,
  path = NULL,
  in.path = path,
  out.path = path,
  fun,
  in.varnames,
  out.varnames,
  na.strings = "NA",
  valid.ranges,
  nodata.values = c(),
  out.nodata.value,
  digits = 4,
  hdr.digits = 10,
  dec = ".",
  quiet = TRUE,
  nlines = Inf,
  na.action = stats::na.exclude,
  pass.location = FALSE,
  ...
)

Arguments

in.grids	character vector: file names of input ASCII grids, relative to in.path; in.grid.prefix will be used as a prefix to the file name if specified; default file extension: .asc
in.grid.prefix	character string (optional), defining a file name prefix to be used for the input file names; a dash (-) will separate the prefix and the in.varnames
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 out.varnames
path	path in which to look for in.grids 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.grids (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; fun is expected to accept named arguments with the names given by in.varnames; grid.predict() is a wrapper function that can be used for applying a model's predict method to a stack of grids; see Details. In multi.local.function, fun must be able to process arguments that are vectors of equal length (e.g., a vector of 50 slope angles, another vector of 50 elevation values, etc.).
in.varnames	character vector: names of the variables corresponding to the in.grids; if missing, same as in.grids; if specified, must have the same length and order as in.grids
out.varnames	character vector specifying the name(s) of the variable(s) returned by fun; if missing, multi.focal.function will try to determine the varnames from fun itself, or 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.ranges	optional list of length length(in.grids) with numeric vector of length 2, specifying minimum and maximum valid values read from input file; all values <valid.ranges[[i]][1] or >valid.ranges[[i]][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 FALSE, 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.
pass.location	logical: Should the x,y coordinates of grid points (center of grid cells) be passed to fun? If TRUE, two additional arguments named arguments x and y are passed to fun; NOTE: This currently only works for radius=0, otherwise a warning is produced and pass.location is reset to FALSE.
...	Arguments to be passed to fun; local.function: arguments to be passed to focal.function.
na.action	function: determines if/how NA values are omitted from the stack of input variables; use na.exclude() (default) or na.pass() if fun can handle NA values correctly

Details

multi.local.function is probably most useful for applying the predict method of a fitted model to a grids representing the predictor variables. An example is given below and in more detail in Brenning (2008) (who used multi.focal.function for the same purpose); see also grid.predict().

multi.local.function is essentially the same as multi.focal.function for radius=0, but coded MUCH more efficiently. (The relevant code will eventually migrate into multi.focal.function as well, but requires further testing.) Applying a GAM to the data set of Brenning (2008) takes about 1/100th the time with multi.local.function compared to multi.focal.function.

multi.focal.function extends focal.function() by allowing multiple input grids to be passed to the focal function fun operating on moving windows. It passes square matrices 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; one such matrix or vector per input grid will be passed to fun as an argument whose name is specified by in.varnames.

These matrices or vectors 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, such as a regression result or a vector of class probabilities returned by a soft classifier. In addition to the named arguments receiving the moving window data, fun may have additional arguments; the ... argument of focal.function is passed on to fun. grid.predict() 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.

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

See focal.function() for details.

Value

multi.focal.function returns the character vector of output file names.

Note

multi.focal.function can do all the things focal.function() can do.

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

focal.function(), grid.predict()

Examples

## Not run: 
# Assume that d is a data.frame with point observations
# of a numerical response variable y and predictor variables
# a, b, and c.
# Fit a generalized additive model to y,a,b,c.
# We want to model b and c as nonlinear terms:
require(gam)
fit <- gam(y ~ a + s(b) + s(c), data = d)
multi.local.function(in.grids = c("a", "b", "c"),
    out.varnames = "pred",
    fun = grid.predict, fit = fit )
    # Note that the 'grid.predict' uses by default the
    # predict method of 'fit'.
# Model predictions are written to a file named pred.asc

## End(Not run)

## Not run: 
# A fake example of a logistic additive model:
require(gam)
fit <- gam(cl ~ a + s(b) + s(c), data = d, family = binomial)
multi.local.function(in.grids = c("a", "b", "c"),
    out.varnames = "pred",
    fun = grid.predict, fit = fit,
    control.predict = list(type = "response") )
    # 'control.predict' is passed on to 'grid.predict', which
    # dumps its contents into the arguments for 'fit''s
    # 'predict' method.
# Model predictions are written to a file named pred.asc

## End(Not run)

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