focal.function {RSAGA} | R Documentation |
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.
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, valid.range = c(-Inf, Inf), 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, ...) local.function(...) gapply(in.grid, fun, varnames, mw.to.vector=TRUE, mw.na.rm=TRUE, ...)
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
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.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 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 . |
... |
Arguments to be passed to fun ;
local.function : arguments to be passed to
focal.function . |
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 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. 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.
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.
focal.function
and local.function
return the
character vector of output file names.
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!
Alexander Brenning
resid.median
, resid.minmedmax
,
relative.position
, resid.quantile
,
resid.quartiles
, relative.rank
,
wind.shelter
, create.variable.name
## 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)