Learn R Programming
⚠️There's a newer version (0.4.3) of this package.Take me there.

[

Rsagacmd - a package for linking R with SAGA-GIS

Rsagacmd provides an R scripting interface to the open-source SAGA-GIS (https://sourceforge.net/projects/saga-gis/) software. The current version has been tested using SAGA-GIS 2.3.2, 5.0.0 - 8.0.1 on Windows (x64), OS X and Linux.

Contents

Description

Rsagacmd provides a complete interface between R and SAGA-GIS. The package allows all SAGA-GIS tools and libraries to be used from within R. Further, the most common geospatial datatypes within R (rasters, simple features, and sp objects) are seamlessly passed between R and SAGA-GIS during geoprocessing operations.

Rsagacmd is unrelated to the RSAGA package (https://cran.r-project.org/package=RSAGA), which provides a command line parser and a subset of pre-defined functions to interface with SAGA-GIS. In contrast, Rsagacmd provides links with SAGA-GIS by dynamically generating R functions for every SAGA-GIS tool that is contained in the user's installed SAGA-GIS version. This means that every SAGA-GIS tool is available for use within R (other than the interactive tools), and Rsagacmd always remains up-to-date with new versions of SAGA-GIS. Custom tools that have been created using SAGA's toolchains (https://rohanfisher.wordpress.com/saga-tool-chains/) will also be accessible via Rsagacmd.

Package installation

CRAN version

Rsagacmd is now available on CRAN. To install this version run :

install.packages("Rsagacmd")

In your R session.

Development version

First install the devtools package:

install.packages("devtools")

Then install Rsagacmd from github:

library(devtools)
install_github("stevenpawley/Rsagacmd")

Usage

The primary function in Rsagacmd is the saga_gis function that returns an object containing all of the SAGA-GIS libraries and tools in the same structure as what is accessible within the GIS software itself. Each tool is nested within its respective library and can be accessed by:

library(Rsagacmd)

# initiate a saga object
saga <- saga_gis()

# access the libraries and tools
saga$ta_morphometry$mass_balance_index()

This facilitates an easier scripting experience by organizing the large number of SAGA-GIS tools (> 700) by their respective library. Each function's syntax is the same as when using the SAGA-GIS command line tool directly except that Rsagacmd always uses lowercase arguments). Furthermore, because the arguments (called identifiers in SAGA-GIS) for many SAGA-GIS tools are not consistently named, the user can also take advantage of code autocompletion tools in Rstudio, allowing for each tools' inputs, outputs and options to be more easily recognized.

Passing geospatial and tabular data between R and SAGA-GIS

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 mapping R functions to execute SAGA-GIS tools, 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, all of the Rsagacmd tools allow paths to the input data to be used as arguments, if the data is stored in the appropriate file formats (GDAL-supported single-band rasters, OGR supported vector data, and comma- or tab-delimited text files for tabular data). In addition, Rsagacmd currently 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 raster package. Raster-based outputs from SAGA-GIS tools are loaded as RasterLayer 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 dataframes.

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

Notes on handing multi-band raster datasets by Rsagacmd and SAGA-GIS

SAGA-GIS does not handle multi-band rasters and 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, specified as either the path to the single raster band, or when using the R raster package, a RasterLayer (or less commonly a RasterStack or RasterBrick) object that contains on-the-fly a single layer. Subsetting of raster data is performed automatically by Rsagacmd in the case of when a single band from a RasterStack or RasterBrick 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. However, a few SAGA-GIS functions will accept a list of single band rasters as an input. In this case if this data is in the form of a RasterStack or RasterLayer object, it is recommended to use the unstack function in the raster package, which will return a list of RasterLayer objects, and then Rsagacmd will handle the subsetting automatically.

Combining SAGA-GIS tools with pipes

For convenience, non-optional outputs from SAGA-GIS are automatically saved to tempfiles if outputs are not explicitly stated, and then loaded as the appropriate R object (RasterLayer, sf object, or a tibble).

This means that Rsagacmd can be used with %>% to quickly chain together complex geoprocessing operations:

saga <- saga_gis()

# Generate random terrain and save to file
dem <- saga$grid_calculus$random_terrain(target_out_grid = "terrain.sgrd")

# Terrain ruggedness index and automatically save the result to a tempfile
tri <- saga$ta_morphometry$terrain_ruggedness_index_tri(dem = dem, radius = 3)

This example will write the output terrain ruggedness index to a temporary file, and will automatically load the result into the R environment as a RasterLayer object. This was implemented for convenience, and so that the user can also create complex workflows that require very little code. It is also means that you can combine several processing steps with pipes:

# read project area as a simple features object
prj_bnd <- st_read('some_shape.shp')
dem <- raster('some_dem.tif')

# clip dem to shape, resample, and calculate potential incoming solar radiation
pisr <- dem %>%
    saga$shapes_grid$clip_grid_with_rectangle(shapes = prj_bnd)) %>%
    saga$grid_tools$resampling(target_user_size = 100) %>%
    saga$ta_lighting$potential_incoming_solar_radiation(
        location = 1, 
        period = 2, 
        day = "2013-01-01", 
        day_stop = "2014-01-01",
        days_step = 10, 
        hour_step = 3, 
        method = 'Hofierka and Suri',
        grd_linke_default = 3
    )

In the above example, three tools are joined together using pipes, and only the PISR grid is returned as a RasterLayer object. The intermediate processing steps are dealt with automatically by saving the outputs as tempfiles. When dealing with high-resolution and/or larger raster data, these tempfiles can start to consume a significant amount of disk space over a session. If required, temporary files can be cleaned during the session in a similar way to the raster package, using:

saga_remove_tmpfiles(h = 0)

where h is minimum age (in number of hours) of tempfiles for removal, so h=0 will remove all tempfiles that were automatically created by Rsagacmd.

The behaviour of automatically outputting results to tempfiles can be disabled for any tool by using .all_outputs = FALSE. In this case, the output arguments need to be specified manually, e.g.:

tri <- saga$ta_morphometry$terrain_ruggedness_index_tri(
    dem = dem, 
    radius = 3, 
    tri = "somefile.sgrd"
)

Copy Link

Version

Install

install.packages('Rsagacmd')

Monthly Downloads

427

Version

0.1.2

License

GPL-3

Maintainer

Steven Pawley

Last Published

December 4th, 2021

Functions in Rsagacmd (0.1.2)

print.saga_tool

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

Prepares the statement and runs the external saga_cmd executable
saga_version

Return the installed version of SAGA-GIS
tile_geoprocessor

Split a raster grid into tiles for tile-based processing
saga_show_tmpfiles

List temporary files created by Rsagacmd
update_parameter_file

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

Objects exported from other packages
saga_env

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

Generates a custom saga_cmd configuration file
parse_options

Convenience function to join together the saga_cmd option:value pairs
parameters

Generates a list of `parameter` objects for a SAGA-GIS tool
saga_remove_tmpfiles

Removes temporary files created by Rsagacmd
create_tool_overrides

Apply manually-defined changes to specific tools
saga_search

Automatic search for the path to a SAGA-GIS installation
tidy.saga_tool

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

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

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

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

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

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

Search for a SAGA-GIS tool
read_grid

Read a raster data set that is output by saga_cmd
save_object

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

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

Read a tabular data set that is output by saga_cmd
read_shapes

Read a spatial vector data set that is output by saga_cmd
update_parameters_tempfiles

Update a `parameters` object using temporary files for any unspecified output parameters
saga_gis

Initiate a SAGA-GIS geoprocessor object
saga_execute

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

Generates list of options for a SAGA-GIS tool
mrvbf_threshold

Calculate the t_slope value based on DEM resolution for MRVBF
parameter

Parameter class
create_alias

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

Function generate text that will be parsed into R code
Rsagacmd

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

Internal function to extract information from a `saga_tool` object
drop_parameters

Drops unused/empty parameters from a `parameters` object
check_output_format

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.