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(s)

Maintainer: Steven Pawley dr.stevenpawley@gmail.com

See Also

Useful links:

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

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

Examples

## Not run: 
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)

## End(Not run)

Check the file extension of the output file to see if it is the same as the 'raster_format' or 'vector_format' settings. If a raster, such as a GeoTIFF is output directly from a SAGA-GIS tool but the raster format is set to SAGA, then this might work depending on the saga version but Rsagacmd will not know how to read the file.

Description

Check the file extension of the output file to see if it is the same as the 'raster_format' or 'vector_format' settings. If a raster, such as a GeoTIFF is output directly from a SAGA-GIS tool but the raster format is set to SAGA, then this might work depending on the saga version but Rsagacmd will not know how to read the file.

Usage

check_output_format(x, raster_format, vector_format)

Arguments

Ensure that the file extension for the SAGA raster format ends with .sdat for reading or writing SAGA grid objects in R.

Description

This is used because the R raster/terra libraries expect to read and write SAGA grid formats using the '.sdat' file extension, not '.sgrd'.

Usage

convert_sagaext_r(fp)

Arguments

Value

a character vector with the corrected file extensions to read SAGA sgrd files back into R.

Generates a syntactically-correct R name based on a SAGA-GIS identifier

Description

SAGA-GIS identifiers sometimes cannot represent syntactically-correct names in R because they start with numbers or have spaces. They are also all in uppercase which is ugly to refer to in code. This function creates an alternative/alias identifier.

Usage

create_alias(identifier)

Arguments

Value

A character with a syntactically-correct alias.

Function generate text that will be parsed into R code

Description

Internal variable 'args' is derived by capturing the names and values of the calling function. The interval 'senv' variable is the SAGA-GIS library settings (generated by 'saga_env') and comes from the environment of when the dynamic function was generated.

Usage

create_function(lib, tool)

Arguments

Value

A character, text that is to be parsed into a function definition.

Generates list of options for a SAGA-GIS tool

Description

Parses the html table for a SAGA-GIS tool into a list of identifiers, options, defaults and constraints

Usage

create_tool(tool_information, tool_options, description, html_file)

Arguments

Value

A 'saga_tool' object containing: + 'tool_name' A syntactically-correct name for the tool. + ‘description' The tool’s description. + ‘author' The tool’s author. + 'tool_cmd' The command to use for saga_cmd to execute tool. + ‘tool_id' The tool’s ID. + ‘parameters' A named list of the tool’s parameter objects. + 'html_file' The html document name.

Apply manually-defined changes to specific tools

Description

Used to manually alter or add parameters for specific tools outside of what has been defined based on the output of saga_cmd –create-docs

Usage

create_tool_overrides(tool_name, params)

Arguments

Value

the altered 'parameters' object

Drops unused/empty parameters from a 'parameters' object

Description

Drops unused/empty parameters from a 'parameters' object

Usage

drop_parameters(params)

Arguments

Value

A 'parameters' object with empty 'parameter' objects removed

Internal function to extract information from a 'saga_tool' object

Description

Internal function to extract information from a 'saga_tool' object

Usage

extract_tool(x)

Arguments

Value

the intervals of a 'saga_tool'

Calculate the t_slope value based on DEM resolution for MRVBF

Description

Calculates the t_slope value for the Multiresolution Index of Valley Bottom Flatness (Gallant and Dowling, 2003) based on input DEM resolution. MRVBF identified valley bottoms based on classifying slope angle and identifying low areas by ranking elevation in respect to the surrounding topography across a range of DEM resolutions. The MRVBF algorithm was developed using a 25 m DEM, and so if the input DEM has a different resolution then the slope threshold t_slope needs to be adjusted from its default value of 16 in order to maintain the relationship between slope and DEM resolution. This function provides a convenient way to perform that calculation.

Usage

mrvbf_threshold(res)

Arguments

Value

numeric, t_slope value for MRVBF

Examples

mrvbf_threshold(res = 10)

Parameter class

Description

Stores metadata associated with each SAGA-GIS tool parameter.

Usage

parameter(type, name, alias, identifier, description, constraints)

Arguments

Value

A 'parameter' class object.

Generates a list of 'parameter' objects for a SAGA-GIS tool

Description

Each 'parameter' object contains information about the datatype, permissible values and input/output settings associated with each identifier for a SAGA-GIS tool.

Usage

parameters(tool_options)

Arguments

Value

A 'parameters' object

Convenience function to join together the saga_cmd option:value pairs

Description

Convenience function to join together the saga_cmd option:value pairs

Usage

parse_options(key, value)

Arguments

Value

character, a joined option:value pair such as "-DEM:mygrid.tif"

Generic function to display help and usage information for any SAGA-GIS tool

Description

Displays a tibble containing the name of the tool's parameters, the argument name used by Rsagacmd, the identifier used by the SAGA-GIS command line, and additional descriptions, default and options/constraints.

Usage

## S3 method for class 'saga_tool'
print(x, ...)

Arguments

Examples

## Not run: 
# Initialize a saga object
saga <- saga_gis()

# Display usage information on a tool
print(saga$ta_morphometry$slope_aspect_curvature)

# Or simply:
saga$ta_morphometry$slope_aspect_curvature

## End(Not run)

Read a raster data set that is output by saga_cmd

Description

Read a raster data set that is output by saga_cmd

Usage

read_grid(x, backend)

Arguments

Value

either a 'raster' or 'SpatRaster' object

Read a semi-colon separated list of grids that are output by saga_cmd

Description

Read a semi-colon separated list of grids that are output by saga_cmd

Usage

read_grid_list(x, backend)

Arguments

Value

list, containing multiple 'raster' or 'SpatRaster' objects.

Primary function to read data sets (raster, vector, tabular) that are output by saga_cmd

Description

Primary function to read data sets (raster, vector, tabular) that are output by saga_cmd

Usage

read_output(output, raster_backend, vector_backend, .intern, .all_outputs)

Arguments

Value

the loaded objects, or NULL is '.intern = FALSE'.

Read a spatial vector data set that is output by saga_cmd

Description

Read a spatial vector data set that is output by saga_cmd

Usage

read_shapes(x, vector_backend)

Arguments

Value

an 'sf' object.

Get path to the example DEM data

Description

Rsagacmd comes bundled with a small tile of example Digital Elevation Model (DEM) data from the NASA Shuttle Radar Topography Mission Global 1 arc second V003. This data is stored in GeoTIFF format in 'inst/extdata'.

Usage

read_srtm()

Details

The dataset contains the land surface elevation of an area located near Jasper, Alberta, Canada, with the coordinate reference system (CRS) EPSG code of 3402 (NAD83(CSRS) / Alberta 10-TM (Forest)).

To access the data, use the convenience function of 'read_srtm()' to load the data as a 'terra::SpatRaster' object.

Examples

library(Rsagacmd)
library(terra)

dem <- read_srtm()
plot(dem)

Read a tabular data set that is output by saga_cmd

Description

Read a tabular data set that is output by saga_cmd

Usage

read_table(x)

Arguments

Value

a 'tibble'.

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

generics

tidy

Prepares the statement and runs the external saga_cmd executable

Description

Prepares the statement and runs the external saga_cmd executable

Usage

run_cmd(saga_cmd, saga_config, lib, tool_cmd, args, verbose)

Arguments

Value

list, output from 'processx::run()'

Generates a custom saga_cmd configuration file

Description

Creates and edits a saga_cmd configuration file in order to change saga_cmd settings related to file caching and number of available processor cores. Intended to be used internally by saga_gis

Usage

saga_configure(
  senv,
  grid_caching = FALSE,
  grid_cache_threshold = 100,
  grid_cache_dir = NULL,
  cores = NULL,
  saga_vers
)

Arguments

Value

A character that specifies the path to custom saga_cmd initiation file.

Browse the online documentation for a saga_tool

Description

Browse the online documentation for a saga_tool

Usage

saga_docs(saga_tool)

Arguments

Examples

## Not run: 
library(Rsagacmd)

saga <- saga_gis()

saga_docs(saga$ta_morphometry$slope_aspect_curvature)

## End(Not run)

Parses valid SAGA-GIS libraries and tools into a nested list of functions

Description

Establishes the link to SAGA GIS by generating a SAGA help file and parsing all libraries, tools and options from the help files into a nested list of library, module and options, that are contained within an saga environment object object. Intended to be used internally by saga_gis

Usage

saga_env(
  saga_bin = NULL,
  opt_lib = NULL,
  raster_backend = "terra",
  vector_backend = "sf"
)

Arguments

Value

A saga environment S3 object containing paths, settings and a nested list of libraries tools and options.

Function to execute SAGA-GIS commands through the command line tool

Description

Intended to be used internally by each function

Usage

saga_execute(
  lib,
  tool,
  senv,
  .intern = NULL,
  .all_outputs = NULL,
  .verbose = NULL,
  ...
)

Arguments

Value

output of SAGA-GIS tool loaded as an R object.

Initiate a SAGA-GIS geoprocessor object

Description

Dynamically generates functions to all valid SAGA-GIS libraries and tools. These functions are stored within a saga S3 object as a named list of functions

Usage

saga_gis(
  saga_bin = NULL,
  grid_caching = FALSE,
  grid_cache_threshold = 100,
  grid_cache_dir = NULL,
  cores = NULL,
  raster_backend = "terra",
  vector_backend = "sf",
  raster_format = "SAGA",
  vector_format = c("ESRI Shapefile", "GeoPackage"),
  all_outputs = TRUE,
  intern = TRUE,
  opt_lib = NULL,
  temp_path = NULL,
  verbose = FALSE
)

Arguments

Value

A S3 'saga' object containing a nested list of functions for SAGA-GIS libraries and tools.

Examples

## Not run: 
# Initialize a saga object
library(Rsagacmd)
library(terra)

saga <- saga_gis()

# Alternatively initialize a saga object using file caching to handle large
# raster files
saga <- saga_gis(grid_caching = TRUE, grid_cache_threshold = 250, cores = 1)

# Example terrain analysis
# Generate a random DEM
dem <- saga$grid_calculus$random_terrain(radius = 100)

# Use Rsagacmd to calculate the Terrain Ruggedness Index
tri <- saga$ta_morphometry$terrain_ruggedness_index_tri(dem = dem)
plot(tri)

# Optionally run command and do not load result as an R object
saga$ta_morphometry$terrain_ruggedness_index_tri(dem = dem, .intern = FALSE)

# Initialize a saga object but do not automatically save all results to
# temporary files to load into R. Use this if you are explicitly saving each
# output because this will save disk space by not saving results from tools
# that output multiple results that you may be want to keep.
saga <- saga_gis(all_outputs = FALSE)

## End(Not run)

Removes temporary files created by Rsagacmd

Description

For convenience, functions in the Rsagacmd package create temporary files if any outputs for a SAGA-GIS tool are not specified as arguments. Temporary files in R are automatically removed at the end of each session. However, when dealing with raster data, these temporary files potentially can consume large amounts of disk space. These temporary files can be observed during a session by using the saga_show_tmpfiles function, and can be removed using the saga_remove_tmpfiles function. Note that this function also removes any accompanying files, i.e. the '.prj' and '.shx' files that may be written as part of writing a ESRI Shapefile '.shp' format

Usage

saga_remove_tmpfiles(h = 0)

Arguments

Value

Nothing is returned.

Examples

## Not run: 
# Remove all temporary files generated by Rsagacmd
saga_remove_tmpfiles(h = 0)

## End(Not run)

List temporary files created by Rsagacmd

Description

For convenience, functions in the Rsagacmd package create temporary files if any outputs for a SAGA-GIS tool are not specified as arguments. Temporary files in R are automatically removed at the end of each session. However, when dealing with raster data, these temporary files potentially can consume large amounts of disk space. These temporary files can be observed during a session by using the saga_show_tmpfiles function, and can be removed using the saga_remove_tmpfiles function.

Usage

saga_show_tmpfiles()

Value

returns the file names of the files in the temp directory that have been generated by Rsagacmd. Note this list of files only includes the primary file extension, i.e. '.shp' for a shapefile without the accessory files (e.g. .prj, .shx etc.).

Examples

## Not run: 
# Show all temporary files generated by Rsagacmd
saga_remove_tmpfiles(h = 0)

## End(Not run)

Return the installed version of SAGA-GIS

Description

Intended to be used internally by saga_env. Uses a system call to saga_cmd to output version of installed SAGA-GIS on the console

Usage

saga_version(saga_cmd)

Arguments

Value

A numeric_version with the version of SAGA-GIS found at the cmd path.

Generic methods to save R in-memory objects to file to SAGA-GIS to access

Description

Designed to be used internally by Rsagacmd for automatically pass data to SAGA-GIS for geoprocessing.

Usage

save_object(x, ...)

Arguments

Value

A character that specifies the file path to where the R object was saved.

Automatic search for the path to a SAGA-GIS installation

Description

Returns the path to the saga_cmd executable.

Usage

search_saga()

Details

On Microsoft Windows, automatic searching will occur first in 'C:/Program Files/SAGA-GIS'; 'C:/Program Files (x86)/SAGA-GIS'; 'C:/SAGA-GIS'; 'C:/OSGeo4W'; and 'C:/OSGeo4W64'.

On Linux, saga_cmd is usually included in PATH, if not an automatic search is performed in the '/usr/' folder.

For macOS, since version 8.5, SAGA-GIS is available as an standalone macOS app from SourceForge. The 'SAGA.app' package is searched first (assuming that it is installed in the '/Applications/' folder). Other macOS locations that are searched include '/usr/local/bin/' (for Homebrew installations) and within the QGIS application (SAGA-GIS is bundled with the QGIS application on macOS by default).

If multiple versions of SAGA-GIS are installed on the system, the path to the newest version is returned.

Value

The path to installed saga_cmd binary.

Search for a SAGA-GIS tool

Description

Search for a SAGA-GIS tool

Usage

search_tools(x, pattern)

Arguments

Value

a tibble containing the libraries, names and parameters of the tools that match the pattern of the search text and their host library

Examples

## Not run: 
# initialize Rsagacmd
saga <- saga_gis()

# search for a tool
search_tools(x = saga, pattern = "terrain")

## End(Not run)

List the available raster formats that can be set as defaults for a 'saga' object.

Description

List the available raster formats that can be set as defaults for a 'saga' object.

Usage

show_raster_formats()

Value

tibble

Examples

show_raster_formats()

List the available vector formats that can be set as defaults for a 'saga' object.

Description

List the available vector formats that can be set as defaults for a 'saga' object.

Usage

show_vector_formats()

Value

tibble

Examples

show_vector_formats()

Interval function used to summarize a 'saga_tool' into a tibble that describes the tools parameters and options

Description

Interval function used to summarize a 'saga_tool' into a tibble that describes the tools parameters and options

Usage

summarize_tool_params(tool_obj)

Arguments

Value

a tibble

Summarize the libraries that are available within a saga object and return these as a tibble.

Description

Summarize the libraries that are available within a saga object and return these as a tibble.

Usage

## S3 method for class 'saga'
tidy(x, ...)

Arguments

Value

a tibble that describes libraries, their descriptions and number of tools that are available in SAGA-GIS.

Examples

## Not run: 
# Initialize a saga object
saga <- saga_gis()

# tidy the saga object's parameters into a tibble
tidy(saga)

## End(Not run)

Summarize the tools that are available within a saga library and return these as a tibble.

Description

Summarize the tools that are available within a saga library and return these as a tibble.

Usage

## S3 method for class 'saga_library'
tidy(x, ...)

Arguments

Value

a tibble that describes the tools and their descriptions within a particular SAGA-GIS library.

Examples

## Not run: 
# Initialize a saga object
saga <- saga_gis()

# tidy the library's parameters into a tibble
tidy(saga$climate_tools)

## End(Not run)

Summarize the parameters that are available within a SAGA-GIS tool and return these as a tibble.

Description

Summarize the parameters that are available within a SAGA-GIS tool and return these as a tibble.

Usage

## S3 method for class 'saga_tool'
tidy(x, ...)

Arguments

Value

a tibble that describes tools, identifiers used by the saga_cmd command line tool, the equivalent argument name used by Rsagacmd, and other options and descriptions.

Examples

## Not run: 
# Initialize a saga object
saga <- saga_gis()

# tidy the tools parameters into a tibble
tidy(saga$ta_morphometry$slope_aspect_curvature)

## End(Not run)

Split a raster grid into tiles for tile-based processing

Description

Split a raster grid into tiles. The tiles are saved as Rsagacmd temporary files, and are loaded as a list of R objects for further processing. This is a function to make the the SAGA-GIS grid_tools / tiling tool more convenient to use.

Usage

tile_geoprocessor(x, grid, nx, ny, overlap = 0, file_path = NULL)

Arguments

Value

A list of SpatRaster objects representing tiled data.

Examples

## Not run: 
# Initialize a saga object
saga <- saga_gis()

# Generate a random DEM
dem <- saga$grid_calculus$random_terrain(radius = 15, iterations = 500)

# Return tiled version of DEM
tiles <- tile_geoprocessor(x = saga, grid = dem, nx = 20, ny = 20)

## End(Not run)

Updates a 'parameter' object with file paths to the R data objects.

Description

Updates a 'parameter' object with file paths to the R data objects.

Usage

update_parameter_file(param, temp_path = NULL, raster_format, vector_format)

Arguments

Value

A 'parameter' object with an updated 'file' attribute that refers to the on-disk file for saga_cmd to access.

Updates a 'parameters' object with file paths to the R data objects.

Description

Updates a 'parameters' object with file paths to the R data objects.

Usage

update_parameters_file(params, temp_path = NULL, raster_format, vector_format)

Arguments

Value

A 'parameters' object with updated 'file' attributes that refers to the on-disk file for saga_cmd to access.

Update a 'parameters' object using temporary files for any unspecified output parameters

Description

Update a 'parameters' object using temporary files for any unspecified output parameters

Usage

update_parameters_tempfiles(params, temp_path, raster_format, vector_format)

Arguments

Value

A 'parameters' object.