rsaga.env: Set up the RSAGA Geoprocessing Environment

Description

rsaga.env creates a list with system-dependent information on SAGA path, module path and data (working) directory. This kind of a list is required by most RSAGA geoprocessing functions and is referred to as the 'RSAGA geoprocessing environment.'

Usage

rsaga.env(workspace = ".", cmd = ifelse(Sys.info()["sysname"] == "Windows", "saga_cmd.exe", "saga_cmd"), path, modules, version, cores, parallel = FALSE, check.libpath = TRUE, check.SAGA = TRUE, check.PATH = Sys.info()["sysname"] == "Windows", check.os.default = TRUE, os.default.path = rsaga.default.path(), lib.prefix)

Arguments

workspace

path of the working directory for SAGA; defaults to the current directory (".").

cmd

name of the SAGA command line program; defaults to saga_cmd.exe, its name under Windows

path

path in which to find cmd; rsaga.env is usually able to find SAGA on your system if it is installed; see Details.

modules

path in which to find SAGA libraries; see Details

version

optional character string: SAGA GIS (API) version, e.g. "2.0.8"; if missing, a call to rsaga.get.version is used to determine version number of SAGA API

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

parallel

optional logical argument (default: FALSE): if TRUE, run RSAGA functions that are capable of parallel processing in parallel mode; note that this is completely independent of the behaviour of SAGA GIS (which can be controlled using the cores argument); currently only some RSAGA functions support parallel processing (e.g., pick.from.ascii.grid or rsaga.get.modules). parallel=TRUE requires that a parallel backend such as doSNOW or doMC is available and has been started prior to calling any parallelized RSAGA function, otherwise warnings may be generated

check.libpath

if TRUE (default), first look for SAGA GIS in the folder where the RSAGA package is installed

check.SAGA

if TRUE (default), next check the path given by the environment variable SAGA, if it exists

check.PATH

if TRUE (default on Windows), next look for SAGA GIS in all the paths in the PATH environment variable; defaults to FALSE on non-Windows OS

check.os.default

if TRUE, look for SAGA GIS in the folder specified by os.default.path.

os.default.path

on Windows, C:/Progra~1/SAGA-GIS; on unix, an attempt is made to locate saga_cmd

lib.prefix

character string: a possible (platform-dependent) prefix for SAGA GIS library names; if missing (recommended), a call to rsaga.lib.prefix tries to determine the correct prefix, e.g. "" on Windows systems and "lib" on non-Windows systems with SAGA GIS pre-2.1.0. Try specifying "" or "lib" manually if this causes problems, and contact the package maintainer if the detection mechanism fails on your system (indicate your Sys.info()["sysname"] and your SAGA GIS version)

Value

A list with components workspace, cmd, path, modules, version, cores and parallel with values as passed to rsaga.env or default values as described in the Details section.

Details

IMPORTANT: Unlike R functions such as options, which changes and saves settings somewhere in a global variable, rsaga.env does not actually 'save' any settings, it simply creates a list that can (and has to) be passed to other rsaga.* functions. See example below.

I strongly recommend to install SAGA GIS in "C:/Program Files/SAGA-GIS" in the case of English-language Windows platforms (the equivalent non-English installation folder in the case of non-English Windows versions seems to work as well). If this is the only SAGA GIS copy on the computer and you do not define a Windows environment variable SAGA, then RSAGA should normally be able to find your SAGA GIS installation in this folder.

rsaga.env tries to collect infromation on the (R)SAGA environment. If path is missing, rsaga.env first looks for an environment variable SAGA; if this is undefined, it checks the current working directory, then the paths given in the PATH environment variable, and finally the function's guess is "C:/Progra~1/SAGA-GIS" (or "/usr/local/bin" on non-Windows systems).

The default modules folder on Windows systems is the modules subfolder of the SAGA binaries' folder. The SAGA_MLB environment variable is not checked by rsaga.env.

On Unix (and Mac OS X) systems, the default modules folder is as specified in the SAGA_MLB environment variable. If this is empty / not set, then the following backup path is used. If path ends with "/bin", then "/bin" is changed to "/lib/saga" and taken as the modules path; otherwise, /usr/local/lib/saga is used.

Examples

Run this code

## Not run: 
# # Check the default RSAGA environment on your computer:
# myenv <- rsaga.env()
# myenv
# # SAGA data in C:/sagadata, binaries in C:/SAGA-GIS, modules in C:/SAGA-GIS/modules:
# myenv <- rsaga.env(workspace="C:/sagadata", path="C:/SAGA-GIS")
# # Unix: SAGA in /usr/bin (instead of the default /usr/local/bin),
# # and modules in /use/lib/saga:
# # myenv <- rsaga.env(path="/usr/bin")
# # Use the 'myenv' environment for SAGA geoprocessing:
# rsaga.hillshade("dem","hillshade",env=myenv)
# # ...creates (or overwrites) grid "C:/sagadata/hillshade.sgrd"
# # derived from digital elevation model "C:/sagadata/dem.sgrd"
# 
# # Same calculation with different SAGA version:
# # (I keep several versions in SAGA-GIS_2.0.x folders:)
# myenv05 = rsaga.env(path = "C:/Progra~1/SAGA-GIS_2.0.5")
# rsaga.hillshade("dem","hillshade205",env=myenv05)
# ## End(Not run)