Skip to contents

Passing R objects as algorithm arguments

Floris Vanderhaeghe

Last update: 2024-06-28
Last run: 2024-10-07

Source: vignettes/qgis_arguments.Rmd
qgis_arguments.Rmd

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:

qgis_get_argument_specs("native:joinbynearest") |> 
  subset(select = name:qgis_type)
#> # A tibble: 9 × 3
#>   name                description                                      qgis_type
#>   <chr>               <chr>                                            <chr>    
#> 1 INPUT               Input layer                                      source   
#> 2 INPUT_2             Input layer 2                                    source   
#> 3 FIELDS_TO_COPY      Layer 2 fields to copy (leave empty to copy all… field    
#> 4 DISCARD_NONMATCHING Discard records which could not be joined        boolean  
#> 5 PREFIX              Joined field prefix                              string   
#> 6 NEIGHBORS           Maximum nearest neighbors                        number   
#> 7 MAX_DISTANCE        Maximum distance                                 distance 
#> 8 OUTPUT              Joined layer                                     sink     
#> 9 NON_MATCHING        Unjoinable features from first layer             sink

String or R object?

Although you can pass a string 1 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.

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.

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). 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.