rsaga.geoprocessor: Generic R interface for SAGA modules
In RSAGA: SAGA Geoprocessing and Terrain Analysis

rsaga.geoprocessor

R Documentation

Generic R interface for SAGA modules

Description

This function is the workhorse of the R–SAGA interface: It calls the SAGA command line tool to run SAGA modules and pass arguments.

Usage

rsaga.geoprocessor(
  lib,
  module = NULL,
  param = list(),
  show.output.on.console = TRUE,
  invisible = TRUE,
  intern = TRUE,
  prefix = NULL,
  flags = ifelse(show.output.on.console, "q", "s"),
  cores,
  env = rsaga.env(),
  display.command = FALSE,
  reduce.intern = TRUE,
  check.module.exists = TRUE,
  warn = options("warn")$warn,
  argsep = " ",
  check.parameters = TRUE,
  ...
)

Arguments

`lib`	Name of the SAGA library to be called (see Details).
`module`	Number (`>=0`) or name of the module to called within the library `lib` (see Details).
`param`	A list of named arguments to be passed to the SAGA module (see Examples).
`show.output.on.console`	a logical (default: `TRUE`), indicates whether to capture the output of the command and show it on the R console (see `system()`).
`invisible`	a logical, indicates whether the command window should be visible on the screen.
`intern`	a logical, indicates whether to make the output of the command an R object
`prefix`	optional character string: prefix such as `"-h"` used in the `saga_cmd` call; mostly for internal purposes; call `saga_cmd -h` from the command line for details; see also `flags`
`flags`	optional character string indicating any command line flags; supported only by SAGA GIS 2.1.0 (and higher), quietly ignored otherwise: `"q"`: no progress report (the default for `show.output.on.console=TRUE`); `"r"`: no messages report; `"s"`: silent mode, i.e. no progress and no messages report (the default for `show.output.on.console=FALSE`); other flag options probably not relevant within RSAGA
`cores`	optional numeric argument, or `NA`: number of cores used by SAGA GIS; supported only by SAGA GIS 2.1.0 (and higher), ignored otherwise (with a warning); overwrites the `cores` setting specified in the `env` argument (see `rsaga.env()`). Multicore-enabled SAGA GIS modules such as the one used by `rsaga.pisr()` seem to run in multicore mode by default when this argument is not specified, therefore `cores` should only be specified to use a smaller number of cores than available on a machine.
`env`	A SAGA geoprocessing environment, i.e. a list with information on the SAGA and SAGA modules paths and the name of the working directory in which to look for input and output files. (Defaults: see `rsaga.env()`.)
`display.command`	Display the DOS command line for executing the SAGA module (including all the arguments to be passed). Default: `FALSE`.
`reduce.intern`	If `intern=TRUE`, reduce the text output of SAGA returned to R by eliminating redundant lines showing the progress of module execution etc. (default: `TRUE`).
`check.module.exists`	logical (default: `TRUE`): call `rsaga.module.exists()` to determine if the specified module can be called in the current SAGA installation
`warn`	logical (default: `TRUE`): for internal purposes - can be used to suppress warning messages generated by failed SAGA_CMD calls; currently used by `rsaga.get.lib.modules()` and related functions; see `options()` argument `warn` for details
`argsep`	character (default: `" "`; currently for internal use): defines the character symbol used as a separator between each argument name and argument value passed to `saga_cmd`. SAGA GIS 2.1.0 (RC1) seems to move toward `"="` as a separator, but `" "` still works and some modules (e.g. the used by `rsaga.pisr`) don't seem to work with `argsep="="`. Future releases of RSAGA may change the default `argsep` value and/or delete or ignore this argument and/or move it to `rsaga.env()`.
`check.parameters`	logical(default: `TRUE`): Check if correct parameters are used.
`...`	Additional arguments to be passed to `base::system()`.

Details

This workhorse function establishes the interface between the SAGA command line program and R by submitting a system call. This is a low-level function that may be used for directly accessing SAGA; specific functions such as rsaga.hillshade are intended to be more user-friendly interfaces to the most frequently used SAGA modules. These higher-level interfaces support default values for the arguments and perform some error checking; they should therefore be preferred if available.

A warning is issued if the RSAGA version is not one of 2.0.4-2.0.8 or 2.1.0-2.1.4

Value

The type of object returned depends on the intern argument passed to system().

If intern=FALSE, a numerical error/success code is returned, where a value of 0 corresponds to success and a non-zero value indicates an error. Note however that the function always returns a success value of 0 if wait=FALSE, i.e. if it does not wait for SAGA to finish.

If intern=TRUE (default), the console output of SAGA is returned as a character vector. This character vector lists the input file names and modules arguments, and gives a more or less detailed report of the function's progress. Redundant information can be cancelled out by setting reduce.intern=TRUE.

Note

Existing output files will be overwritten by SAGA without prompting!

If a terrain analysis function is not directly interfaced by one of the RSAGA functions, you might still find it in the growing set of SAGA libraries and modules. The names of all libraries available in your SAGA installation can be obtained using rsaga.get.libraries() (or by checking the directory listing of the modules folder in the SAGA directory). The names and numeric codes of all available modules (globally or within a specific library) are retrieved by rsaga.get.modules(). Full-text search in library and module names is performed by rsaga.search.modules(). For information on the usage of SAGA command line modules, see rsaga.get.usage(), or the RSAGA interface function if available.

display.command=TRUE is mainly intended for debugging purposes to check if all arguments are passed correctly to SAGA CMD.

Author(s)

Alexander Brenning (R interface); Olaf Conrad and the SAGA development team (SAGA development)

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 and L. Montanarella (eds.), SAGA - Seconds Out (= Hamburger Beitraege zur Physischen Geographie und Landschaftsoekologie, vol. 19), p. 23-32.

Examples

## Not run: 
rsaga.hillshade("dem","hillshade",exaggeration=2)
# using the RSAGA geoprocessor:
rsaga.geoprocessor("ta_lighting",0,list(ELEVATION="dem.sgrd",SHADE="hillshade",EXAGGERATION=2))
# equivalent DOS command line call:
# saga_cmd.exe ta_lighting 0 -ELEVATION dem.sgrd -SHADE hillshade -EXAGGERATION 2

## End(Not run)

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