5. Advanced specification

2.1 Introduction

Advanced specification is a new feature of the 3.x versions of the plugin. This type of configuration has a different logic than the usual way of specifying parameters, because the structure is different.

In this part of the tutorial we will study the advantages of using the advanced specification in a script.

Let's get started!

Structure and logic

Just as in the normal specification the parameter lines had a structure, so too the advanced specification has a structure that must be maintained. The structure follows this logic:

1##QgsProcessingParameter<Tipo>|Nombre|Descripción|<Otros Argumentos separados pipe>

It starts with two hash signs (##), followed by the class name of the parameter in the QGIS API (QgsProcessingParameter*) and the arguments of the class separated by a vertical bar (|). To understand this structure we must know the QGIS API, either the C version or the Python. What we have to look for are the details of the QgsProcessingParameter<type> classes: Here is a table with the QGIS classes and the corresponding Processing R input parameter.

Advanced specification for outputs

Four types of output parameters are currently supported for advanced specification:

• QgsProcessingParameterRasterDestination
• QgsProcessingParameterVectorDestination
• QgsProcessingParameterFileDestination
• QgsProcessingParameterFolderDestination

Including in a script

In order to understand how to use the advanced specification we will convert the built-in script Min_Max that comes with the QGIS Processing R plugin into a script with advanced specification.

The lines we are interested in changing are 3 and 4:

 1##Example scripts=group
 2##Min_Max=name
 3##Layer=vector
 4##Field=Field Layer
 5##Min=output number
 6##Max=output number
 7##Summary=output string
 8
 9Min <- min(Layer[[Field]])
10Max <- max(Layer[[Field]])
11Summary <- paste(Min, "to", Max, sep = " ")

This is how the tool currently looks like. The arrows indicate the parts where our changes will have an effect.

Let's start changing then the line ##Layer=vector for another one where the variable is still called "Layer", but the description is a more descriptive text, for example "Capa de entrada". Then we will also change the line ##Field=Field Layer, where we specify that it is of type "Number" to avoid problems with text fields.

 1##Example scripts=group
 2##Min_Max=name
 3##QgsProcessingParameterFeatureSource|Layer|Capa de entrada
 4##QgsProcessingParameterField|Field|Variable|None|Layer|0|False|False
 5##Min=output number
 6##Max=output number
 7##Summary=output string
 8
 9Min <- min(Layer[[Field]])
10Max <- max(Layer[[Field]])
11Summary <- paste(Min, "to", Max, sep = " ")

The replacement for line three is ##QgsProcessingParameterFeatureSource|Layer|Capa de entrada for which only the parameter type, variable name and description have been defined. But if you look at the API, that class has five arguments. What happened to the others?.

1QgsProcessingParameterFeatureSource(
2    name: str, 
3    description: str = ‘’, 
4    types: Iterable[int] = [], 
5    defaultValue: Any = None, 
6    optional: bool = False
7    ) 

Unspecified parameters have default values that can be dispensed with in the specification. This works because the assignment of the values is positional. In the case of line 4, it happens that the fifth and sixth arguments need to be specified, so you must write all the other values (at least) until you match the correct position for the value you want to change. In this case, the parent layer of the field and the field type.

 1QgsProcessingParameterField(
 2    name: str, 
 3    description: str = ‘’, 
 4    defaultValue: Any = None, 
 5    parentLayerParameterName: str = ‘’, 
 6    type: QgsProcessingParameterField.DataType = QgsProcessingParameterField.Any, 
 7    allowMultiple: bool = False, 
 8    optional: bool = False, 
 9    defaultToAllFields: bool = False
10    )

The image below shows the effects on the tool. Note that the text descriptions have changed and also the options in the list of possible fields have been reduced.

Practice: Advanced specification

Now it is time to practice. Your task will be to change one or several lines of the script "Zonal mean from top N" available in the workshop scripts. The example data are available thanks to the kind contribution of Castillo, L. (2022)².

Here are the steps you can follow:

1. Right click on the script "Zonal mean from top N" and click on Edit script....
2. In the window that opens you have the whole script, but we are only interested in lines 4 to 8. You can decide which of them you want to try to change.
3. Depending on the line you have chosen you can go to the QGIS API documentation and look for the corresponding arguments for that parameter. Here you have shortcuts to help you:
   • Line 4: raster
   • Line 5: vector polygon
   • Line 6: Field Zonas
   • Line 7: number 100
   • Line 8: output vector
4. Add a documentation line with the key #' ALG_CREATOR:<Your name>, to know who made the modification.
5. When you have finished editing save your changes and test your tool.

 1##Taller UseR!2022=group
 2##zonalmeantopn=name
 3##Zonal mean from top N=display_name
 4#Raster=raster
 5##QgsProcessingParameterRasterLayer|Raster|Capa raster
 6##QgsProcessingParameterFeatureSource|Zonas|Capa vector de zonas|2|None|False
 7##QgsProcessingParameterField|Zonas_Ids|Campo de identificador único de zonas|None|Zonas|-1
 8##QgsProcessingParameterNumber|Top_N|Número máximo de valores más altos|0|100|False|1
 9##QgsProcessingParameterVectorDestination|Zonal|Capa de promedio por zona
10
11Zonas_rst <- raster::rasterize(Zonas, Raster, field = Zonas_Ids)
12mean_top_100 <- function(x, top = Top_N, na.rm = TRUE) {
13  if(na.rm) x <- na.omit(x)
14  if(length(x) < top) {
15    top <- length(x)
16    message("Zone has less than top n values defined. Calculating with availables")
17  }
18  mean(x[which(rank(-x) <= top)][seq_len(top)])
19}
20Stats <- raster::zonal(Raster, Zonas_rst, fun = mean_top_100)
21colnames(Stats) <- c(Zonas_Ids, paste0("mean_", Top_N))
22Zonal <- merge(Zonas, Stats, by = Zonas_Ids)
23
24#'Raster: Capa raster
25#'Zonas: Capa vector de polígonos que representan las zonas
26#'Zonas_Ids: Campo de la capa de <em>Zonas</em>
27#'Top_N: Valor numérico entero que define los n de valores más altos. 
28#'Zonal: Salida vectorial con el promedio de las <em>n</em> valores más altos
29#'ALG_CREATOR: @gavg712

Translations:

• "Español" |