-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy pathREADME.Rmd
250 lines (194 loc) · 9.63 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
---
output: github_document
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# Rsagacmd
<!-- badges: start -->
[](https://cran.r-project.org/package=Rsagacmd)
[
[](https://app.codecov.io/gh/stevenpawley/Rsagacmd?branch=master)
[](https://github.com/stevenpawley/Rsagacmd/actions)
[](https://lifecycle.r-lib.org/articles/stages.html#stable)
<!-- badges: end -->
# **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 - 9.5.1 on Windows (x64), OS X and
Linux.
## Contents
- [Description](#description)
- [Package installation](#package-installation)
- [Usage](#usage)
- [Passing geospatial and tabular data between R and
SAGA-GIS](#passing-geospatial-and-tabular-data-between-r-and-saga-gis)
- [Notes on handing multi-band raster datasets by **Rsagacmd** and
SAGA-GIS](#notes-on-handing-multi-band-raster-datasets-by-**Rsagacmd**-and-saga-gis)
- [Combining SAGA-GIS tools with pipes](#combining-saga-gis-tools-with-pipes)
- [Notes](#notes)
## 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:
```{r, install-cran, eval=FALSE}
install.packages("Rsagacmd")
```
In your R session.
#### Development version
First install the `devtools` package:
```{r, install-devtools, eval=FALSE}
install.packages("devtools")
```
Then install **Rsagacmd** from github:
```{r, install-from-github, eval=FALSE}
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:
```{r getting-started}
library(Rsagacmd)
library(terra)
# initiate a saga object
saga <- saga_gis(raster_backend = "terra")
# load the example data
srtm <- read_srtm()
# access the libraries and tools
saga$ta_morphometry$mass_balance_index(dem = srtm)
```
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 **terra** package as the default
backend. Raster-based outputs from SAGA-GIS tools are loaded as `SpatRaster`
objects. For more details, see the 'Handling of raster data'. Other raster
backends can be specified when creating the link to SAGA-GIS using
`saga_gis(raster_backend = "stars")` for example.
- Vector features that result from SAGA-GIS geoprocessing operations are
output the format specified by the 'vector_format' arguments (default is ESRI
Shapefile for SAGA-GIS versions < 7.0 and GeoPackage for newer versions) and are
loaded into the R environment as simple features (`sf`) objects. Different
vector backends are also supported, including 'sf', 'SpatVector', and
'SpatVectorProxy', which can also be specified when initiating the link to
SAGA-GIS using `saga_gis(vector_backend = "SpatVector")`.
- Tabular data from SAGA-GIS tools are loaded as tibbles
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.
Subsetting of raster data is performed automatically by **Rsagacmd** in the case
of when a single band from a `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, 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 (e.g., `SpatRaster`, `sf` object, or a tibble).
This means that **Rsagacmd** can be used with `%>%` to quickly chain together
complex geoprocessing operations:
```{r using-tempfiles}
# Generate random terrain and save to file
dem <- saga$grid_calculus$random_terrain(
target_out_grid = tempfile(fileext = ".sgrd")
)
# Terrain ruggedness index and automatically save the result to a tempfile
tri <- saga$ta_morphometry$terrain_ruggedness_index_tri(dem = dem, radius = 3)
plot(tri)
```
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 `SpatRaster`
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:
```{r using-pipes}
library(sf)
# read project area as a simple features object
prj_bnd <- st_polygon(list(matrix(
c(320000, 340000, 5880000, 5900000),
nrow = 1
)))
prj_bnd <-
st_bbox(c(xmin = 320000, xmax = 340000, ymin = 5890000, ymax = 5910000)) %>%
st_set_crs(3402) %>%
st_as_sfc()
prj_bnd <- st_as_sf(data.frame(area = "my area"), prj_bnd)
dem <- read_srtm()
# clip dem to shape, resample, and calculate land surface parameters
lsps <- dem %>%
saga$shapes_grid$clip_grid_with_rectangle(shapes = prj_bnd) %>%
aggregate(fact = 2, fun = "mean") %>%
saga$ta_morphometry$slope_aspect_curvature()
plot(lsps$slope)
```
In the above example, three tools are joined together using pipes, and only the
land surface parameter grids are returned as `SpatRaster` objects. 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 using:
```{r removing-tempfiles}
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 specific tool by using `.all_outputs = FALSE` or can be disabled
globally when the link to SAGA-GIS is created using `saga_gis(all_outputs =
FALSE)`. In this case, the output arguments need to be specified manually, e.g.:
```{r explicit-outputs}
tri <- saga$ta_morphometry$terrain_ruggedness_index_tri(
dem = dem,
radius = 3,
tri = tempfile(fileext = ".sgrd"),
.all_outputs = FALSE
)
```