multi.focal.function {RSAGA} | R Documentation |
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. 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.
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, dec = ".", quiet = TRUE, nlines = Inf, mw.to.vector = FALSE, mw.na.rm = FALSE, pass.location = FALSE, ... )
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.factor.grid |
optional file name giving a gridded categorical variables defining zones; zone boundaries are used as breaklines for the moving window (see Details) |
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 |
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.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. |
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 NA s
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. |
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 NA s 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 . |
na.strings |
passed on to scan |
... |
Arguments to be passed to fun ;
local.function : arguments to be passed to
focal.function . |
multi.focal.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); see also grid.predict
.
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 NA
s 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 NA
s 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.
multi.focal.function
returns the
character vector of output file names.
multi.focal.function
can do all the things focal.function
can do.
Alexander Brenning
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. http://www.environment.uwaterloo.ca/u/brenning/Brenning-2008-RSAGA.pdf
## 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.focal.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.focal.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)