Merge pull request #186 from r-spatial/various

Smaller improvements

.github/workflows/R-CMD-check.yaml

@@ -23,8 +23,9 @@ jobs:
           - {os: windows-latest, qgis: 'none', r: 'devel', dep: '', r-pkg-cache: 'v11'}
           - {os: ubuntu-22.04, qgis: 'none', r: 'release', dep: '', r-pkg-cache: 'v11'}
           - {os: macOS-latest, qgis: 'macos-brew', r: 'release', dep: '', r-pkg-cache: 'v0'}
-          - {os: windows-latest, qgis: 'windows-chocolatey', r: 'release', dep: '', r-pkg-cache: 'v0'}
-          - {os: windows-latest, qgis: 'windows-chocolatey', r: 'devel', dep: '', r-pkg-cache: 'v2'}
+          - {os: windows-latest, qgis: 'chocolatey', r: 'release', dep: '', r-pkg-cache: 'v0'}
+          - {os: windows-latest, qgis: 'chocolatey-ltr', r: 'release', dep: '', r-pkg-cache: 'v0'}
+          - {os: windows-latest, qgis: 'chocolatey', r: 'devel', dep: '', r-pkg-cache: 'v2'}
           - {os: ubuntu-22.04, qgis: 'ubuntu-nightly', r: 'release', dep: '', r-pkg-cache: 'v0'}
           - {os: ubuntu-22.04, qgis: 'ubuntu-nightly', r: 'devel', dep: '', r-pkg-cache: 'v2'}
           - {os: ubuntu-22.04, qgis: 'ubuntugis', r: 'release', dep: '', r-pkg-cache: 'v1'}
@@ -45,7 +46,6 @@ jobs:
       - uses: r-lib/actions/setup-r@v2
         with:
           r-version: ${{ matrix.config.r }}
-          http-user-agent: ${{ matrix.config.http-user-agent }}
           use-public-rspm: true
           extra-repositories: https://geocompr.r-universe.dev
 
@@ -115,11 +115,17 @@ jobs:
           sudo cp -R qgis/QGIS.app /Applications
 
       - name: Install QGIS (Windows chocolatey)
-        if: matrix.config.qgis == 'windows-chocolatey'
+        if: matrix.config.qgis == 'chocolatey'
         uses: crazy-max/ghaction-chocolatey@v2
         with:
           args: install qgis
 
+      - name: Install QGIS LTR (Windows chocolatey)
+        if: matrix.config.qgis == 'chocolatey-ltr'
+        uses: crazy-max/ghaction-chocolatey@v2
+        with:
+          args: install qgis-ltr
+
       - name: Query R dependencies and report available versions
         id: query
         if: matrix.config.dep == ''

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: qgisprocess
 Title: Use 'QGIS' Processing Algorithms
-Version: 0.1.0.9179
+Version: 0.1.0.9180
 Authors@R: c(
     person("Dewey", "Dunnington", , "[email protected]", role = "aut",
            comment = c(ORCID = "0000-0002-9415-4582", affiliation = "Voltron Data")),

NEWS.md

@@ -4,6 +4,7 @@
 - Allow half-configured states with abundant messages, so that remaining functionality can be used in debugging or even for some real stuff (#177).
 - Add vector support for {terra} (#184).
 This makes it possible to use SpatVector(Proxy) objects as input arguments, and to coerce processing results to SpatVector(Proxy).
+- `qgis_run_algorithm()` documentation gains a section on QGIS models and scripts (8a20669).
 
 # qgisprocess 0.1.0
 

R/qgis-run-algorithm.R

@@ -5,6 +5,50 @@
 #' for a detailed description of the algorithms provided
 #' 'out of the box' on QGIS.
 #'
+#' `qgis_run_algorithm()` accepts various R objects as algorithm 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
+#' raster/terra/stars objects for the argument type 'raster', but there are many
+#' more.
+#' `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.
+#'
+#' @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.
+#' This will put the model or script below the provider 'Models' or
+#' 'Scripts', respectively.
+#' Next, it is necessary to run [qgis_configure()] in R in order to make the
+#' model or script available to qgisprocess (even reloading the package won't
+#' detect it, since these providers have dynamic content, not tied to a
+#' plugin or to a QGIS version).
+#' You can check the outcome with [qgis_providers()] and
+#' [qgis_search_algorithms()].
+#' Now, just as with other algorithms, you can provide the `model:<name>` or
+#' `script:<name>` identifier to the `algorithm` argument of
+#' `qgis_run_algorithm()`.
+#'
+#' As the output argument name of a QGIS model can have an R-unfriendly
+#' syntax, you may need to take the JSON parameter string from the QGIS
+#' processing dialog and feed the JSON string to the `.raw_json_input` argument
+#' of `qgis_run_algorithm()` instead of providing separate arguments.
+#'
+#' Although the 'qgis_process' backend also supports replacing the 'algorithm'
+#' parameter by the file path of a model file or a Python script, it is not
+#' planned to implement this in qgisprocess, as it would bypass argument
+#' preprocessing in R (including checks).
+#'
 #' @family functions to run one geoprocessing algorithm
 #'
 #' @param algorithm A qualified algorithm name (e.g., `"native:buffer"`) or

tests/testthat/test-qgis-algorithms.R

@@ -12,18 +12,6 @@ test_that("qgis_algorithms() works", {
   expect_true(all(vapply(algs[old_names], function(x) all(!is.na(x)), logical(1))))
 })
 
-test_that("qgis_has_algorithm() works", {
-  skip_if_not(has_qgis())
-  expect_true(qgis_has_algorithm("native:filedownloader"))
-  expect_false(qgis_has_algorithm("notanalgorithm"))
-})
-
-test_that("qgis_has_provider() works", {
-  skip_if_not(has_qgis())
-  expect_true(qgis_has_provider("native"))
-  expect_false(qgis_has_provider("notaprovider"))
-})
-
 test_that("qgis_providers() works", {
   skip_if_not(has_qgis())
   expect_s3_class(qgis_providers(), "data.frame")

tests/testthat/test-qgis-configure.R

@@ -1,55 +1,3 @@
-test_that("qgis_version() works", {
-  skip_if_not(has_qgis())
-
-  expect_match(qgis_version(), "^\\d{1,2}\\.\\d+.*-.+")
-  expect_match(qgis_version(full = FALSE), "^\\d{1,2}\\.\\d+.\\d+$")
-})
-
-test_that("qgis_version(debug = TRUE) works", {
-  skip_if_not(has_qgis())
-  skip_if(
-    package_version(qgis_version(full = FALSE)) < "3.22.0",
-    "QGIS version is older than 3.22.0"
-  )
-
-  capture.output({
-    expect_message(
-      qgis_version(debug = TRUE),
-      glue("Using.+{getNamespaceVersion('qgisprocess')}")
-    )
-    expect_message(qgis_version(debug = TRUE), "PROJ version")
-    expect_message(qgis_version(debug = TRUE), "EPSG ")
-  })
-})
-
-test_that("qgis_query_version() works", {
-  skip_if_not(has_qgis())
-
-  expect_match(qgis_query_version(), "^\\d{1,2}\\.\\d+.*-.+")
-})
-
-test_that("qgis_query_version() works for development versions of QGIS", {
-  skip_if_not(has_qgis())
-  qversion <- qgis_query_version()
-  skip_if_not(
-    stringr::str_detect(
-      qversion,
-      "^\\d{1,2}\\.\\d*[13579][\\.-]"
-    ),
-    paste("QGIS version", qversion, "is not a development version.")
-  )
-
-  expect_match(
-    qversion,
-    "^\\d{1,2}\\.\\d+.*-\\p{L}+, development state ([0-9a-f]{7,}|unclear:.+)",
-    perl = TRUE
-  )
-
-  if (stringr::str_detect(qversion, ".+development state unclear:.+")) {
-    expect_warning(qgis_query_version(), "version identifier")
-  }
-})
-
 test_that("qgis_configure() returns FALSE with no QGIS", {
   skip_if(has_qgis())
   expect_false(

tests/testthat/test-qgis-has.R

@@ -0,0 +1,17 @@
+test_that("qgis_has_algorithm() works", {
+  skip_if_not(has_qgis())
+  expect_true(qgis_has_algorithm("native:filedownloader"))
+  expect_false(qgis_has_algorithm("notanalgorithm"))
+})
+
+test_that("qgis_has_provider() works", {
+  skip_if_not(has_qgis())
+  expect_true(qgis_has_provider("native"))
+  expect_false(qgis_has_provider("notaprovider"))
+})
+
+test_that("qgis_has_plugin() works", {
+  skip_if_not(has_qgis())
+  expect_true(qgis_has_plugin("processing"))
+  expect_false(qgis_has_plugin("notaplugin"))
+})

tests/testthat/test-qgis-plugins.R

@@ -68,13 +68,6 @@ test_that("message_disabled_plugins() works", {
 })
 
 
-test_that("qgis_has_plugin() works", {
-  skip_if_not(has_qgis())
-  expect_true(qgis_has_plugin("processing"))
-  expect_false(qgis_has_plugin("notaplugin"))
-})
-
-
 test_that("qgis_enable_plugins() messages are OK", {
   skip_if_not(has_qgis())
   expect_message(qgis_enable_plugins(names = ""), "exiting")

tests/testthat/test-qgis-state.R

@@ -0,0 +1,51 @@
+test_that("qgis_version() works", {
+  skip_if_not(has_qgis())
+
+  expect_match(qgis_version(), "^\\d{1,2}\\.\\d+.*-.+")
+  expect_match(qgis_version(full = FALSE), "^\\d{1,2}\\.\\d+.\\d+$")
+})
+
+test_that("qgis_version(debug = TRUE) works", {
+  skip_if_not(has_qgis())
+  skip_if(
+    package_version(qgis_version(full = FALSE)) < "3.22.0",
+    "QGIS version is older than 3.22.0"
+  )
+
+  capture.output({
+    expect_message(
+      qgis_version(debug = TRUE),
+      glue("Using.+{getNamespaceVersion('qgisprocess')}")
+    )
+    expect_message(qgis_version(debug = TRUE), "PROJ version")
+    expect_message(qgis_version(debug = TRUE), "EPSG ")
+  })
+})
+
+test_that("qgis_query_version() works", {
+  skip_if_not(has_qgis())
+
+  expect_match(qgis_query_version(), "^\\d{1,2}\\.\\d+.*-.+")
+})
+
+test_that("qgis_query_version() works for development versions of QGIS", {
+  skip_if_not(has_qgis())
+  qversion <- qgis_query_version()
+  skip_if_not(
+    stringr::str_detect(
+      qversion,
+      "^\\d{1,2}\\.\\d*[13579][\\.-]"
+    ),
+    paste("QGIS version", qversion, "is not a development version.")
+  )
+
+  expect_match(
+    qversion,
+    "^\\d{1,2}\\.\\d+.*-\\p{L}+, development state ([0-9a-f]{7,}|unclear:.+)",
+    perl = TRUE
+  )
+
+  if (stringr::str_detect(qversion, ".+development state unclear:.+")) {
+    expect_warning(qgis_query_version(), "version identifier")
+  }
+})

vignettes/qgis_expressions.Rmd

@@ -1,7 +1,9 @@
 ---
 title: "How to use QGIS expressions in qgisprocess?"
 author: "Floris Vanderhaeghe & Jannes Muenchow"
-date: "Last updated: 2023-08-16"
+date: |
+  | Last update: 2023-08-16
+  | Last run: `r Sys.Date()`
 output: rmarkdown::html_vignette
 vignette: >
   %\VignetteIndexEntry{How to use QGIS expressions in qgisprocess?}

vignettes/qgisprocess.Rmd

@@ -1,7 +1,9 @@
 ---
 title: "Getting started with qgisprocess"
 author: "Jannes Muenchow & Floris Vanderhaeghe"
-date: "Last updated: 2023-08-16"
+date: |
+  | Last update: 2023-08-16
+  | Last run: `r Sys.Date()`
 output:
   html_document: 
     toc: yes