Description Usage Arguments Details Value Note Author(s) References See Also Examples

`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.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 | ```
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, ...)
``` |

`in.grids` |
character vector: file names of input ASCII grids, relative to |

`in.grid.prefix` |
character string (optional), defining a file name prefix to be used for the input file names; a dash ( |

`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 ( |

`path` |
path in which to look for |

`in.path` |
path in which to look for |

`out.path` |
path in which to write output grid files; defaults to |

`fun` |
a function, or name of a function, to be applied on the moving window; see Details; |

`in.varnames` |
character vector: names of the variables corresponding to the |

`out.varnames` |
character vector specifying the name(s) of the variable(s) returned by |

`radius` |
numeric value specifying the (circular or square) radius of the moving window; see |

`is.pixel.radius` |
logical: if |

`na.strings` |
passed on to |

`valid.ranges` |
optional list of length |

`nodata.values` |
numeric vector: any values from the input grid file that should be converted to |

`out.nodata.value` |
numeric: value used for storing |

`search.mode` |
character, either |

`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 |

`dec` |
character, specifying the decimal mark to be used for input and output. |

`quiet` |
If |

`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 |

`pass.location` |
logical: Should the x,y coordinates of grid points (center of grid cells) be passed to |

`...` |
Arguments to be passed to |

`na.action` |
function: determines if/how |

`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 `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.

`focal.function()`

, `grid.predict()`

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 | ```
## 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)
``` |

Embedding an R snippet on your website

Add the following code to your website.

For more information on customizing the embed code, read Embedding Snippets.