Rsagacmd: saga_gis – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

saga_gis

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,
  backend = "raster",
  raster_format = "SAGA",
  vector_format = "ESRI Shapefile",
  all_outputs = TRUE,
  intern = TRUE,
  opt_lib = NULL,
  temp_path = NULL,
  verbose = FALSE
)

Arguments

`saga_bin`	The path to saga_cmd executable. If this argument is not supplied then an automatic search for the saga_cmd executable will be performed.
`grid_caching`	A logical whether to use file caching in saga_cmd geoprocessing operations for rasters that are too large to fit into memory.
`grid_cache_threshold`	A number to act as a threshold (in Mb) before file caching is activated for loaded raster data.
`grid_cache_dir`	The path to directory for temporary files generated by file caching. If not provided then the result from 'base::tempdir()' is used.
`cores`	An integer for the maximum number of processing cores. By default all cores are utilized. Needs to be set to 1 if file caching is activated.
`backend`	A character vector to specify the library to use for handling raster data. Currently, either "raster" or "terra" is supported. The default is "raster".
`raster_format`	A character to specify the default format used to save raster data sets that are produced by SAGA-GIS. Available options are one of "SAGA", "SAGA Compressed" or "GeoTIFF". The default is "SAGA".
`vector_format`	A character to specify the default format used to save vector data sets that are produced by SAGA-GIS. Available options are of of "ESRI Shapefile", "GeoPackage", or "GeoJSON". The default is "ESRI Shapefile".
`all_outputs`	A logical to indicate whether to automatically use temporary files to store all output data sets from each SAGA-GIS tool. Default = TRUE. This argument can be overridden by the '.all_outputs' parameter on each individual SAGA-GIS tool function that is generated by 'Rsagacmd::saga_gis()'.
`intern`	A logical to indicate whether to load the SAGA-GIS geoprocessing results as an R object, default = TRUE. For instance, if a raster grid is output by SAGA-GIS then this will be loaded as either as 'RasterLayer' or 'SpatRaster' object, depending on the 'backend' setting that is used. Vector data sets are always loaded as 'sf' objects, and tabular data sets are loaded as tibbles. The 'intern' settings for the 'saga' object can be overriden for individual tools using the '.intern' argument.
`opt_lib`	A character vector with the names of a subset of SAGA-GIS libraries. Used to link only a subset of named SAGA-GIS tool libraries, rather than creating functions for all available tool libraries.
`temp_path`	The path to use to store any temporary files that are generated as data is passed between R and SAGA-GIS. If not specified, then the system 'base::tempdir()' is used.
`verbose`	Logical to indicate whether to output all messages made during SAGA-GIS commands to the R console. Default = FALSE. This argument can be overriden by using the '.verbose' argument on each individual SAGA-GIS tool function that is generated by 'Rsagacmd::saga_gis()'.

Value

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

Examples

## Not run: 
# Initialize a saga object
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)

Rsagacmd

Linking R with the Open-Source 'SAGA-GIS' Software

v0.1.0

GPL-3

Authors

Steven Pawley [aut, cre]

Initial release

2021-01-08