Rsagacmd (version 0.4.3)

Rsagacmd: Rsagacmd: Linking R with the open-source SAGA-GIS software.

Description

Rsagacmd provides an R scripting interface to the open-source System for Automated Geoscientific Analyses Geographical Information System software SAGA-GIS. The current version has been tested using SAGA-GIS versions 2.3.1 to 9.2 on Windows (x64), macOS and Linux. Rsagacmd provides a functional approach to scripting with SAGA-GIS by dynamically generating R functions for every SAGA-GIS tool based on the user's current SAGA-GIS installation. These functions are generated by the saga_gis function and are included within an S3 object as a named list of libraries and tools. This structure facilitates an easier scripting experience by organizing the large number of SAGA-GIS tools (>700) by their respective library. Interactive scripting can also fully take advantage of code autocompletion tools (e.g. in Rstudio), allowing for each tool's syntax to be quickly recognized. Furthermore, the most common types of spatial data (rasters using the terra and stars packages, and vector data using sp, sf or terra packages) along with non-spatial data are seamlessly passed from R to the SAGA-GIS command line tool for geoprocessing operations, and the results are automatically loaded as the appropriate R object. Outputs from individual SAGA-GIS tools can also be chained using pipes from the magrittr and dplyr packages to chain complex geoprocessing operations together in a single statement.

Handling of geospatial and tabular data

Rsagacmd aims to facilitate a seamless interface to the open-source SAGA-GIS by providing access to all SAGA-GIS geoprocessing tools in a 'R-like' manner. In addition to generating R functions that correspond to each SAGA-GIS tool, Rsagacmd automatically handles the passing of geospatial and tabular data contained from the R environment to SAGA-GIS.

Rsagacmd uses the SAGA-GIS command line interface to perform geoprocessing operations. Therefore, spatial data can be passed to any Rsagacmd function as a path to the input data, assuming that the data is stored in the appropriate file formats (e.g. GDAL-supported single-band rasters, OGR supported vector data, and comma- or tab-delimited text files for tabular data). In addition, Rsagacmd also supports the following R object classes to pass data to SAGA-GIS, and to load the results back into the R environment:

• Raster data handling is provided by the R terra and stars packages. Raster-based outputs from SAGA-GIS tools are loaded as SpatRaster or stars objects. For more details, see the 'Handling of raster data'.

• Vector features that result from SAGA-GIS geoprocessing operations are output in ESRI Shapefile format and are loaded into the R environment as simple features objects

• Tabular data from SAGA-GIS tools are loaded as data frames

The results from tools that return multiple outputs are loaded into the R environment as a named list of the appropriate R object classes.

Multi-band raster data

SAGA-GIS does not handle multi-band rasters and the native SAGA GIS Binary file format (.sgrd) supports only single band data. Therefore when passing raster data to most SAGA-GIS tools using Rsagacmd, the data should represent single raster bands. Subsetting of raster data is performed automatically by Rsagacmd in the case of when a single band from a multiband SpatRaster or stars object is passed to a SAGA-GIS tool. This occurs in by either passing the filename of the raster to the SAGA-GIS command line, or by writing the data to a temporary file.

Combining SAGA-GIS tools with pipes

For convenience, outputs from SAGA-GIS tools are automatically saved to tempfiles if outputs are not explicitly stated as arguments when calling the function. This was implemented so that the user can create complex workflows based on little code. It is also means that several processing steps can be combined or chained in a convenient manner using pipes from the magritrr package. When using pipes, all of the intermediate processing steps are dealt with automatically by saving the outputs as tempfiles, and then in turn passing the output to the next function in the chain. Note that when dealing with high-resolution and/or larger raster data, these tempfiles can start to consume a significant amount of disk space during a session. If required, these temporary files can be cleaned during the session using the saga_remove_tmpfiles function.

Author

Maintainer: Steven Pawley

See Also

Useful links:

• https://stevenpawley.github.io/Rsagacmd/

• Report bugs at https://github.com/stevenpawley/Rsagacmd/issues

Examples

if (FALSE) {
library(Rsagacmd)
library(magrittr)

# initialize a saga object
saga <- saga_gis(opt_lib = c("grid_calculus", "ta_morphometry"))

# example of executing a tool using a tempfile to store the tool outputs
dem <- saga$grid_calculus$random_terrain(radius = 100, iterations = 500)

# Example of chaining operations using pipes and using tempfile to
# store tool outputs
tri <- dem %>%
  saga$ta_morphometry$terrain_ruggedness_index_tri()

# Remove tempfiles generated by Rsagacmd during a session
saga_remove_tmpfiles(h = 0)
}