Merge pull request #213 from r-spatial/vign

Add vignettes on algorithm arguments + options; update qgis_run_algorithm() docs

Author: florisvdh

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: qgisprocess
 Title: Use 'QGIS' Processing Algorithms
-Version: 0.3.0.9002
+Version: 0.3.0.9003
 Authors@R: c(
     person("Dewey", "Dunnington", , "dewey@fishandwhistle.net", role = "aut",
            comment = c(ORCID = "0000-0002-9415-4582", affiliation = "Voltron Data")),

NEWS.md

@@ -4,6 +4,9 @@
 This benefits package startup time and the timing of `qgis_run_algorithm()`, `qgis_show_help()`, and several other functions.
 This feature needs QGIS >= 3.36.
 - Don't renew the package cache when no plugins were successfully enabled or disabled (#212).
+- Add new vignettes (#213):
+  - `vignette("qgis_arguments")`: passing R objects as algorithm arguments.
+  - `vignette("qgis_options")`: configuration with options or environment variables.
 - Update the 'getting started' vignette (#206, #207):
   - advise to use `qgis_search_algorithms()`.
   - in QGIS >= 3.36 the GRASS GIS provider is called `grass` instead of `grass7`.

R/qgis-run-algorithm.R

@@ -6,6 +6,7 @@
 #' 'out of the box' on QGIS.
 #'
 #' `qgis_run_algorithm()` accepts various R objects as algorithm arguments.
+#' An overview is given by `vignette("qgis_arguments")`.
 #' Examples include an R matrix or data frame for the
 #' argument type 'matrix', R colors for the argument type 'color',
 #' sf or terra (SpatVector) objects for the argument type 'vector' and
@@ -14,16 +15,20 @@
 #' `qgis_run_algorithm()` preprocesses the provided objects into the format that
 #' QGIS expects for a given argument.
 #'
-#' For data objects in R that already exist as a stored file, it is best to
-#' instead provide the file path in order to prevent a superfluous file writing
-#' step from R, as QGIS expects a file path.
-#' However terra and stars objects can contain the file path as metadata: in
-#' these cases this path is retrieved from the R object and passed to QGIS;
-#' potential pitfalls are taken care of.
-#'
 #' Providing R objects that cannot be converted to the applicable argument type
 #' will lead to an error.
 #'
+#' Algorithm arguments can be passed as arguments of [qgis_run_algorithm()], but
+#' they can also be combined as a JSON string and fed into the `.raw_json_input`
+#' argument.
+#' A JSON string can be obtained from the QGIS GUI, either from the
+#' processing tool dialog or from the processing history dialog, by selecting
+#' 'Copy as JSON' in the 'Advanced' dropdown menu.
+#' So a user can first try out a geoprocessing step in the QGIS GUI, and
+#' once the chosen algorithm arguments are satisfactory, copy the JSON string
+#' to reproduce the operation in R.
+#' A screenshot is available at the package homepage.
+#'
 #' @section Running QGIS models and Python scripts:
 #' QGIS models and Python scripts can be added to the Processing Toolbox in the
 #' QGIS GUI, by pointing at their corresponding file.
@@ -51,6 +56,8 @@
 #'
 #' @family functions to run one geoprocessing algorithm
 #'
+#' @seealso `vignette("qgis_arguments")`
+#'
 #' @param algorithm A qualified algorithm name (e.g., `"native:buffer"`) or
 #'   a path to a QGIS model file.
 #' @param PROJECT_PATH,ELLIPSOID Global values for QGIS project file and
@@ -61,6 +68,7 @@
 #' @param .quiet Use `FALSE` to get extra output from 'qgis_process'.
 #' This can be useful in debugging.
 #' @param .raw_json_input The raw JSON to use as input in place of `...`.
+#' See _Details_ section.
 #'
 #' @returns A `qgis_result` object.
 #'

man/qgis_run_algorithm.Rd

@@ -0,0 +1,97 @@
+```{r setup, message=FALSE}
+library(qgisprocess)
+```
+
+This article addresses the question how algorithm arguments in `qgis_run_algorithm()` should be formatted.
+
+When you run `qgis_show_help()` or `qgis_get_argument_specs()` for a given algorithm, you will quickly find out that QGIS has a diverse set of possible argument types.
+
+As an example, take a look at the `qgis_type` column below:
+
+```{r}
+qgis_get_argument_specs("native:joinbynearest") |> 
+  subset(select = name:qgis_type)
+```
+
+# String or R object?
+
+Although you can pass a string [^string] to a QGIS argument in `qgis_run_algorithm()`, `{qgisprocess}` makes it possible to pass familiar R objects that naturally match the QGIS argument type.
+This is often easier than constructing a string in the format required by QGIS.
+
+[^string]: A string is a character vector of length 1.
+
+The tables further below show which R objects can be passed to each QGIS argument type!
+You can find a bit more background information in issue [#13](https://github.com/r-spatial/qgisprocess/issues/13).
+
+# Defaults
+
+Some arguments will receive a default value if they are unspecified.
+Defaults are provided by either `{qgisprocess}` or QGIS.
+Typical defaults by `{qgisprocess}` are temporary filepaths for (missing) output argument types `sink`, `vectorDestination`, `rasterDestination`, `fileDestination` and `folderDestination`.
+
+# Supported R objects
+
+## For spatial QGIS arguments
+
+QGIS argument type | Supported R object
+-- | -----
+`source`, `vector` | a string (filepath) or an appropriate spatial vector object (`sf`, `SpatVector`, `SpatVectorProxy`)
+`raster` | a string (filepath) or an appropriate spatial raster object (`SpatRaster`, `stars`, `stars_proxy`, `RasterLayer`, `RasterBrick`)
+`layer` |  a string (filepath) or an appropriate spatial object (`sf`, `SpatVector`, `SpatVectorProxy`, `SpatRaster`, `stars`, `stars_proxy`, `RasterLayer`, `RasterBrick`)
+`multilayer` | a list of layers created by `qgis_list_input()` (alternatively, repeat the same argument providing each layer in turn)
+`aggregates`, `field_mapping`, `tininputlayers`, `vectortilewriterlayers` | a nested list created by `qgis_list_input()` (unnamed list) or `qgis_dict_input()` (named list) or a combination of both (a `native:aggregate` example is found [here](https://github.com/r-spatial/qgisprocess/issues/133#issuecomment-1488490056)). These argument types are typically not supported by the legacy (no-JSON) input method.
+`point` | a vector of 2 point coordinates, a simple feature geometry (`sfg`) of class `POINT`, or an `sfc` (geometry set) or `sf` object with exactly one `POINT` geometry
+`band` | an integer value
+`extent` | a vector of the form `c(xmin, xmax, ymin, ymax)`, a `bbox` object from `{sf}`, a `SpatExtent` object from `{terra}` or an `Extent` object from `{raster}`
+`crs` | a `crs` object from `{sf}`, a `CRS` object from `{raster}` or a WKT2 string (e.g. obtained with `terra::crs()`)
+`coordinateoperation` | PROJ string of a coordinate operation, possibly obtained using `sf::sf_proj_pipelines()`
+`sink`, `vectorDestination` | a string: filepath to a vector file format (defaults to a temporary GeoPackage if argument is missing)
+`rasterDestination` | a string: filepath to a raster file format (defaults to a temporary GeoTIFF file if argument is missing)
+
+### Note
+
+An important group of spatial QGIS argument types are those used in specifying an input layer.
+QGIS essentially needs a filepath string here.
+If a spatial R object is provided instead, `{qgisprocess}` will:
+
+- either write out the object to a temporary file and pass the filepath to QGIS,
+- or use the object's filepath metadata if present (supported by some classes of `{terra}` and `{stars}`).
+
+However if the spatial R object simply results from reading a spatial file and if its filepath is _not_ included in the object's metadata (e.g. for `sf` or `SpatVector` objects), then you will get most efficiency if you pass the original filepath directly.
+
+## For non-spatial QGIS arguments
+
+QGIS argument types | Supported R object
+-- | -----
+`enum` | a character vector with one or more acceptable string values. A numeric vector with the corresponding index number(s) can also be provided, but contrary to the character vector its acceptability won't be checked.
+`range` | a vector of length 2, defining minimum and maximum value respectively
+`file`, `field`, `layout`, `layoutitem`, `maptheme`, `execute_sql` | string
+`string` | any string, including data-defined overriding (`"field:..."` or `"expression:..."`)
+`distance`, `number` | numeric (length 1), or a string for data-defined overriding (`"field:..."` or `"expression:..."`)
+`boolean` | logical (length 1), or a string for data-defined overriding (`"field:..."` or `"expression:..."`)
+`color` | a colour string that `col2rgb()` understands (e.g. `"pink1"` or `"#1A664D80"`), or a string for data-defined overriding (`"field:..."` or `"expression:..."`)
+`expression`, `raster_calc_expression` | a string (formatted as `"expression:..."`). See `vignette("qgis_expressions")`.
+`matrix` | a matrix or a data frame with contents as required by the algorithm
+`relief_colors` | a matrix or a data frame with three columns and with rows corresponding to intervals. The first two columns define the interval (minimum and maximum respectively) and the third column must be a colour string that `col2rgb()` understands (e.g. `"pink1"` or `"#1A664D80"`).
+`fileDestination`, `folderDestination` | a string: path to a file or directory (defaults to a temporary file or directory if argument is missing)
+
+# Passing output from a previous processing step
+
+The object returned by `qgis_run_algorithm()` is a `qgis_result`.
+It contains one or several _output elements_, shown when printing the `qgis_result` object.
+
+A single output element can be extracted with `qgis_extract_output()`, and it has one of the following classes: 
+`qgis_outputFile`,
+`qgis_outputFolder`,
+`qgis_outputLayer`,
+`qgis_outputMultilayer`,
+`qgis_outputNumber`,
+`qgis_outputRaster`,
+`qgis_outputString` or
+`qgis_outputVector`.
+
+These objects essentially represent a string.
+They can be passed directly to an appropriate argument in a next `qgis_run_algorithm()` step.
+
+Also note that the pipe-friendly function `qgis_run_algorithm_p()` (notice the `_p`) is able to accept an 'incoming' `qgis_result` object as its first argument.
+It will extract the appropriate output element on the fly.

man/vignette_childs/_qgis_arguments.Rmd

@@ -0,0 +1,28 @@
+---
+title: "Passing R objects as algorithm arguments"
+author: "Floris Vanderhaeghe"
+date: |
+  | Last update: 2024-06-28
+  | Last run: `r Sys.Date()`
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Passing R objects as algorithm arguments}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+can_build <- qgisprocess::has_qgis()
+```
+
+```{r child=if (can_build) file.path(rprojroot::find_root(rprojroot::is_r_package), "man/vignette_childs/_qgis_arguments.Rmd")}
+```
+
+```{r eval=!can_build, echo=FALSE, results="asis"}
+cat("This vignette has been built in absence of a QGIS installation.\n\n")
+cat("Read it online at <https://r-spatial.github.io/qgisprocess/articles/qgis_arguments.html>.")
+```

vignettes/qgis_arguments.Rmd

@@ -0,0 +1,67 @@
+---
+title: "Configuration with options or environment variables"
+author: "Floris Vanderhaeghe"
+date: |
+  | Last update: 2024-06-28
+  | Last run: `r Sys.Date()`
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Configuration with options or environment variables}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+Options and environment variables are available to manage `{qgisprocess}` behaviour.
+Several options have a corresponding environment variable.
+When both have a value, the _option_ will be given priority.
+
+Options are typically harder to isolate from the R code that you collaborate on.
+Consequently, it is advised to:
+
+- use `options()` where this affects behaviour that must be the same across
+users and machines for reproducibility.
+Put these inside your script, or at least in a `.Rprofile` file that is
+shared together with the other project files.
+- use environment variables where behaviour must be machine-specific.
+For example, you can create a `.Renviron` file in your working directory
+and ignore it in distributed version control.
+Or you can set the environment variable at a higher level, e.g. in a
+`.Renviron` file in your home directory.
+See `base::Startup` for more information.
+
+# Overview
+
+Below table lists the available options and environment variables.
+
+Option | Environment variable | Type
+-- | -- | --
+`qgisprocess.path` | `R_QGISPROCESS_PATH` | string (filepath)
+`qgisprocess.tmp_vector_ext` | not available | string (file extension)
+`qgisprocess.tmp_raster_ext` | not available | string (file extension)
+`qgisprocess.detect_newer_qgis` | `R_QGISPROCESS_DETECT_NEWER_QGIS` | logical
+`qgisprocess.use_json_input` | `R_QGISPROCESS_USE_JSON_INPUT` | logical 
+`qgisprocess.use_json_output` | `R_QGISPROCESS_USE_JSON_OUTPUT` | logical
+`qgisprocess.cachefiles_days_keep` | `R_QGISPROCESS_CACHEFILES_DAYS_KEEP` | numeric
+`qgisprocess.use_cached_help` | `R_QGISPROCESS_USE_CACHED_HELP` | logical
+`qgisprocess.env` | not available | named list
+
+# Descriptions
+
+Following descriptions are applicable to both option and environment variable:
+
+- `qgisprocess.path`: sets the path to 'qgis_process'; see `qgis_configure()`
+- `qgisprocess.tmp_vector_ext`: sets the vector file extension for temporary files; see `qgis_tmp_vector()`
+- `qgisprocess.tmp_raster_ext`: sets the raster file extension for temporary files; see `qgis_tmp_raster()`
+- `qgisprocess.detect_newer_qgis`: for Windows and macOS; will report availability of an installed (standalone) QGIS version that is more recent than the cached version
+- `qgisprocess.use_json_input`: control whether the JSON input method is used; see `qgis_using_json_input()`
+- `qgisprocess.use_json_output`: control whether the JSON output method is used; see `qgis_using_json_output()`
+- `qgisprocess.cachefiles_days_keep`: control a cache file's age (as days) that must be exceeded for it to be deleted when loading the package (default is 90); see `?qgis_delete_old_cachefiles`
+- `qgisprocess.use_cached_help`: whether to fetch an algorithm's documentation from a cached file (corresponding to the QGIS and `{qgisprocess}` versions in use) if this file exists (default is `TRUE`; if `FALSE`, always (re)query documentation from QGIS)
+- `qgisprocess.env`: named list of environment variable values used in each call to 'qgis_process'; see `qgis_run()`