-
Notifications
You must be signed in to change notification settings - Fork 4
/
README.Rmd
96 lines (61 loc) · 4.75 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
---
output: md_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/",
out.width = "100%"
)
```
# qgis
<!-- badges: start -->
[](https://lifecycle.r-lib.org/articles/stages.html#maturing)
[](https://github.com/JanCaha/r_package_qgis/blob/master/DESCRIPTION)
[](https://github.com/JanCaha/r_package_qgis/blob/master/LICENSE.md)
[](https://github.com/JanCaha/r_package_qgis/actions/workflows/build_package.yaml)
[](https://github.com/JanCaha/r_package_qgis/actions/workflows/make_web.yaml)
<!-- badges: end -->
**qgis** is automatically generated package which originates from [qgisprocess](https://github.com/r-spatial/qgisprocess) and aims to provide calls and simple documentation for each [QGIS](https://qgis.org/en/site/) functions available in core and the most important algorithm providers ([GRASS GIS](https://grass.osgeo.org/) and [Saga](http://www.saga-gis.org/)). The algorithms are automatically extracted from fresh install of latest **QGIS** version on **Ubuntu** with packages for **GRASS** and **SAGA** installed.
The package is highly experimental and things are quite likely to change a lot in the future. The definition of individual functions can change if it changes in the QGIS.
## Latest version
Latest package version **`r desc::desc_get_field("Version")`** is build against QGIS version **`r qgisprocess::qgis_version()`**.
## Installation
You can install the released version of **qgis** from GitHub with:
``` r
# install.package("remotes")
remotes::install_github("JanCaha/r_package_qgis")
```
The information about local installation are in a vignette `vignette("local_instalation")`.
## Using/Loading the package
The idea of the package is that it should not be loaded directly using `library(qgis)` but rather functions should be called using `qgis::function_name()` syntax. Even though tests showed ([see them here](https://github.com/JanCaha/r_package_qgis/issues/32#issuecomment-1431139318)) that loading the package does not takes significant amount of resources. The author's suggestion is still to avoid loading and use the `package::function()` notation.
## Functions names
The names of the functions follow general pattern of `algorithm-provider_algorithm-id` with only the native **QGIS** algorithms using `qgis` algorithm provider instead of `native`.
```{r, echo=FALSE, warning=FALSE, message=FALSE}
algs <- readr::read_csv(here::here("data-raw", "algorithms.csv"))
```
The available providers are: `r glue::glue_collapse(unique(algs$provider), sep = ", ")`. The overall number of available algorithms is `r nrow(algs)`.
## Functions parameters
Every functions carries three boolean parameters that allow better utilization of these functions in R pipelines and reports. These are `.complete_output`, `.quiet` and `.messages`. The default setting of these variables is such that the calls are as silent as possible and create pretty much no output in R console at all.
Parameter `.quiet` (default values is `TRUE`) is the same as in `qgisprocess::qgis_run_algorithm()` only in `qgis` the functions are silent by default while in `qgisprocess` they are talkative.
Parameter `.messages` (default value is `FALSE`) controls if messages produced by `qgisprocess` (such as information about parameters not being set etc.) should be outputed or not.
Parameter `.complete_output`(default values is `TRUE`) specifies whether whole QGIS process output should be returned or only first variable in it, which is usually the main output.
These three parameters can also be set as R session options using `options(qgis.quiet = TRUE)`, `options(qgis.messages = FALSE)` and `options(qgis.complete_output = TRUE)` to avoid the need to set them for every individual function call.
## Example
```{r, eval=FALSE}
qgis::qgis_buffer()
```
This allows you to show the help page for the function (at least in **RStudio** using the key shortcut **F1**).
## Example in the wild
This example uses `qgisprocess` pipe ability to directly load output to **R**.
```{r}
library(sf)
nc <- st_read(system.file("shape/nc.shp", package="sf"), quiet = TRUE)
buffered <- qgis::qgis_buffer(INPUT = nc,
DISTANCE = 0.2,
END_CAP_STYLE = "Flat") %>%
st_as_sf()
plot(buffered["NAME"])
```