u

Rsagacmd.Rcheck/00_pkg_src/Rsagacmd/DESCRIPTION

@@ -0,0 +1,46 @@
+Package: Rsagacmd
+Type: Package
+Title: Linking R with the Open-Source 'SAGA-GIS' Software
+Version: 0.4.2
+Date: 2023-10-15
+Authors@R: c(
+    person("Steven", "Pawley",
+    email = "dr.stevenpawley@gmail.com",
+    role = c("aut", "cre")))
+Maintainer: Steven Pawley <dr.stevenpawley@gmail.com>
+Description: Provides an R scripting interface to the open-source 'SAGA-GIS' 
+    (System for Automated Geoscientific Analyses Geographical Information
+    System) software. 'Rsagacmd' dynamically generates R functions for every
+    'SAGA-GIS' geoprocessing tool based on the user's currently installed
+    'SAGA-GIS' version. These functions are contained within an S3 object
+    and are accessed as a named list of libraries and tools. This structure
+    facilitates an easier scripting experience by organizing the large number
+    of 'SAGA-GIS' geoprocessing tools (>700) by their respective library.
+    Interactive scripting can fully take advantage of code autocompletion tools
+    (e.g. in 'Rstudio'), allowing for each tools syntax to be quickly
+    recognized. Furthermore, the most common types of spatial data (via the
+    'terra', 'sp', and 'sf' packages) along with non-spatial data are
+    automatically passed from R to the 'SAGA-GIS' command line tool for
+    geoprocessing operations, and the results are 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 combine complex
+    geoprocessing operations together in a single statement. 'SAGA-GIS' is
+    available under a GPLv2 / LGPLv2 licence from
+    <https://sourceforge.net/projects/saga-gis/> including Windows x86/x64
+    and macOS binaries. SAGA-GIS is also included in Debian/Ubuntu default software
+    repositories. Rsagacmd has currently been tested on 'SAGA-GIS' versions
+    from 2.3.1 to 9.2 on Windows, Linux and macOS.
+License: GPL-3
+Encoding: UTF-8
+SystemRequirements: SAGA-GIS (>= 2.3.1)
+RoxygenNote: 7.2.3
+Depends: R (>= 2.10)
+Imports: generics, sf, terra (>= 1.7.0), stars, tools, utils, foreign,
+        stringr, rlang, tibble, processx, rvest
+Suggests: dplyr, testthat (>= 3.0.0), covr
+Config/testthat/edition: 3
+URL: https://stevenpawley.github.io/Rsagacmd/
+BugReports: https://github.com/stevenpawley/Rsagacmd/issues
+NeedsCompilation: no
+Packaged: 2023-10-15 16:57:18 UTC; stevenpawley
+Author: Steven Pawley [aut, cre]

Rsagacmd.Rcheck/00_pkg_src/Rsagacmd/NAMESPACE

@@ -0,0 +1,37 @@
+# Generated by roxygen2: do not edit by hand
+
+S3method(print,saga_tool)
+S3method(save_object,SpatRaster)
+S3method(save_object,SpatVector)
+S3method(save_object,SpatVectorProxy)
+S3method(save_object,SpatialLinesDataFrame)
+S3method(save_object,SpatialPointsDataFrame)
+S3method(save_object,SpatialPolygonsDataFrame)
+S3method(save_object,character)
+S3method(save_object,data.frame)
+S3method(save_object,default)
+S3method(save_object,list)
+S3method(save_object,sf)
+S3method(save_object,stars)
+S3method(tidy,saga)
+S3method(tidy,saga_library)
+S3method(tidy,saga_tool)
+export(convert_sagaext_r)
+export(extract_tool)
+export(mrvbf_threshold)
+export(read_srtm)
+export(saga_docs)
+export(saga_execute)
+export(saga_gis)
+export(saga_remove_tmpfiles)
+export(saga_show_tmpfiles)
+export(saga_version)
+export(save_object)
+export(search_saga)
+export(search_tools)
+export(show_raster_formats)
+export(show_vector_formats)
+export(summarize_tool_params)
+export(tidy)
+export(tile_geoprocessor)
+importFrom(generics,tidy)

Rsagacmd.Rcheck/00_pkg_src/Rsagacmd/NEWS.md

@@ -0,0 +1,99 @@
+# Rsagacmd 0.42
+
+Minor bug fixes:
+
+- Fixed issue with reading using the terra SpatVector backend.
+- Change to the saga_cmd syntax by referring to a tool by its ID rather than 
+its name, where possible. This avoids confusion with tools that have interactive
+versions.
+- Added package-level documentation.
+
+# Rsagacmd 0.41
+
+Minor fix to only pass character vectors to 'numeric_version'
+
+# Rsagacmd 0.4
+
+Changes:
+
+ - Removed dependencies for raster and rgdal apackages
+
+# Rsagacmd 0.2
+
+New features:
+
+- Support for SpatVector and SpatVectorProxy proxy objects for vector spatial
+datasets.
+
+- tidy methods to summarize information about the SAGA-GIS libraries and tools
+within any library and return these as a tibble.
+
+- Function 'saga_docs' to browse the online documentation for each SAGA-GIS
+tool.
+
+Changes:
+
+ - Bug fix for using the `terra` package as a raster backend.
+
+# Rsagacmd 0.1.2
+
+New features:
+
+- The `search_tool` function now returns a `tibble` containing the tools that
+contain the matching term along with additional metadata including the author of
+the tool, a description and the tool's parameters.
+
+- The generic `tidy` S3 method from the `generics` package has been extended
+with a tidy.saga_tool method that summarizes a SAGA-GIS tool object's parameters
+into a tibble. This is designed for easy viewing of a tools options.
+
+Changes:
+
+- Fix for difference in syntax/parameters between the SAGA GUI and command line
+affecting the TPI tool. The manual/docs list the parameters as specified in the
+GUI, but these differ from those on the command line.
+
+# Rsagacmd 0.1.1
+
+New features:
+
+- Included support for the 'stars' raster backend.
+
+Changes:
+
+- Because 'Rsagacmd' now supports multiple raster backends, the 'raster' package
+is no longer automatically attached when using Rsagacmd. The raster/terra/stars
+objects resulting from geoprocessing operations be still be loaded, but to apply
+additional functions to these objects (e.g. plot) then the user needs to
+explicitly load the desired backend, e.g. `library(stars)` in their script.
+
+- The spinner is now turned off for geoprocessing operations because to avoid
+creating an annoying extra line in Rmarkdown notebooks, jupyter etc.
+
+- Rsagacmd now checks the file extensions of tools to ensure that the correct
+file extension is used relative to the `raster_format` or `vector_format`. This
+ensures that outputs of SAGA-GIS tools will be correctly loaded by R.
+
+- Rsagacmd saga_search should correctly recognize the location of the saga_cmd
+binary on macOS that is included within the QGIS.app bundle, if installed from
+official sources.
+
+# Rsagacmd 0.1.0
+
+Rsagacmd 0.1.0 includes many behind-the-scenes changes that organize the the
+internal representation of SAGA-GIS tools and parameter settings using a similar
+approach as used by the saga_api.
+
+Most notably, this release provides support for the use of different raster
+backend, including the existing 'raster' package, as well as the newer 'terra'
+package. Configuration options to use different spatial formats as data is
+passed from R to SAGA (and back) is also provided. For rasters, datasets that
+are saved from R memory to disk for access by the saga command line (and vice
+versa) can be in 'SAGA' format (the default), 'SAGA Compressed', or 'GeoTIFF',
+which can potentially save disk space when transferring large volumes of data.
+Vector formats now include 'ESRI Shapefile' (the default), 'Geopackage' and
+'GeoJSON'. The use of the geopackage format eliminates problems when
+transferring spatial datasets which have attribute names that are >10 characters
+in length.
+
+Enjoy!

Rsagacmd.Rcheck/00_pkg_src/Rsagacmd/R/Rsagacmd-package.R

@@ -0,0 +1,95 @@
+#' Rsagacmd: Linking R with the open-source SAGA-GIS software.
+#'
+#' \pkg{Rsagacmd} provides an R scripting interface to the open-source System
+#' for Automated Geoscientific Analyses Geographical Information System software
+#' \href{https://sourceforge.net/projects/saga-gis/}{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 \code{\link{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
+#' \href{https://posit.co}{Rstudio}), allowing for each tool's syntax to
+#' be quickly recognized. Furthermore, the most common types of spatial data
+#' (rasters using the \pkg{terra} and \pkg{stars} packages, and vector data
+#' using \pkg{sp}, \pkg{sf} or \pkg{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 \pkg{magrittr} and \pkg{dplyr} packages to chain
+#' complex geoprocessing operations together in a single statement.
+#'
+#' @section 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:
+#' \itemize{
+#' \item Raster data handling is provided by the R \pkg{terra} and \pkg{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'.
+#' \item 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
+#' \item 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.
+#'
+#' @section 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.
+#'
+#' @section 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 \pkg{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.
+#'
+#' @examples
+#' \dontrun{
+#' 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)
+#' }
+#' @name Rsagacmd
+#' @keywords internal
+"_PACKAGE"

Rsagacmd.Rcheck/00_pkg_src/Rsagacmd/R/data-formats.R

@@ -0,0 +1,44 @@
+supported_raster_formats <- c(
+  `SAGA` = ".sgrd",
+  `SAGA Compressed` = ".sg-grd-z",
+  `GeoTIFF` = ".tif"
+)
+
+
+supported_vector_formats <- c(
+  `ESRI Shapefile` = ".shp",
+  `GeoPackage` = ".gpkg",
+  `GeoJSON` = ".geojson"
+)
+
+
+#' List the available raster formats that can be set as defaults for a `saga`
+#' object.
+#'
+#' @return tibble
+#' @export
+#'
+#' @examples
+#' show_raster_formats()
+show_raster_formats <- function() {
+  tibble::tibble(
+    driver = names(supported_raster_formats),
+    extension = supported_raster_formats
+  )
+}
+
+
+#' List the available vector formats that can be set as defaults for a `saga`
+#' object.
+#'
+#' @return tibble
+#' @export
+#'
+#' @examples
+#' show_vector_formats()
+show_vector_formats <- function() {
+  tibble::tibble(
+    driver = names(supported_vector_formats),
+    extension = supported_vector_formats
+  )
+}