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

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

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

`in.grid` |
file name of input ASCII grid, relative to |

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

`varnames` |
character vector specifying the names 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.range` |
numeric vector of length 2, specifying minimum and maximum valid values read from input file; all values |

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

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

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

`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

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.

`multi.focal.function()`

, `multi.local.function()`

, `resid.median()`

, `resid.minmedmax()`

, `relative.position()`

, `resid.quantile()`

, `resid.quartiles()`

, `relative.rank()`

, `wind.shelter()`

, `create.variable.name()`

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

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.