Writing R Processing Scripts

Author

Barry Rowlingson

The plan for this worksheet is to build reusable scripts that work with the R Processing plugin and hence can even be added to a model pipeline. This lets QGIS users with no R skill run complex statistical code.

If you’ve not installed the R Processing plugin, do that first - some help is available in our installation guide.

Download the Course Materials and extract from the zip file for the datasets etc needed here.

The Data and The Problem

In England and Wales, the police forces record reported crimes and make the anonymised data public. This gives us a crime type, date, and approximate location. Our data set consists of bicycle thefts in London in 2024 and 2025. We want to know if there’s been a change in the pattern of thefts in those years.

The supplied GeoPackage contains a layer of points called bike_theft with the locations. There’s also a polygon layer of London boroughs and one of a simple London outline. Load these into QGIS and you can style them, and add a background map. I like the VersaTiles Graybeard map available from the NextGIS QuickMapServices plugin for data analysis, as it is greyscale and enables colour overlays.

The theft data was downloaded from data.police.uk and boundaries for London and its boroughs can be found on the UK Geoportal. Both datasets are available under the Open Government License.

Explore the theft data a bit. Using the identifier tool you might notice there are multiple thefts at the same location - the police adjust actual locations for anonymity. Here you can see 6 thefts recorded at a location in Edmonton.

Bike Thefts in North London

Building a Script

Menu items for R Processing scripts live in QGIS’ processing toolbox. Open the toolbox panel from the Processing menu or hit Control-Alt-T (or the Apple equivalent). At the top of the toolbox there will be a set of icons including an R logo.

R Processing Menu Button

Click the button, and use the Create New R Script... item - its the only one on that button.

An editor window will open up. Scripts for the R Processing provider are basically plain R code with some special comments at the start so that the Processing toolbox knows what sort of input and output data the script needs. Here is a complete script. Enter this into the editor and save it to the folder it defaults to when you hit the Save icon (its a floppy disc, ask your parents…) and name it mean.rsx. R processing uses .rsx for its scripts and saves them together in a folder in your QGIS profile.

##First Test=name
##Test Scripts=group

##Nvalues=number 100

v = runif(Nvalues)
m = mean(v)
message("mean = ",m)

Running a Script

Now you can execute the script. Find your script in the drop-down menu in the list of available algorithms. Towards the bottom of the list you’ll see an R group, and expanding that shows the group mentioned in the script and an entry with the name you gave in the script.

R Scripts Menu

Double-click to execute, or right-click and choose Execute.... This will first produce a dialog where you can see the script location on the right and define the parameters you specified in the script on the left. In this case there’s one numeric parameter called Nvalues and its default is 100. Change it, or leave it, and press Run.

Parameter Setting Menu

Things will happen in the Log tab and there should be a final Algorithm 'First Test' finished message (I get a bunch of warning messages because of how I’ve set R up, you might not see these). Within the text you should see the output message telling you the mean of your sample of numbers.

Algorithm Run Log

Add a Layer Parameter

The previous script had one parameter which was a numeric value that the user could adjust before running the script, and this appeared in the R script as a numeric variable. The framework also allows us to transfer spatial data from QGIS layers to the R script in a similar way.

For example, to produce a script that prompts for a vector layer when run, you would add this metadata comment to the start of the script:

##PointEvents=vector

When executed, this will add a layer chooser to the dialog box.

Script Parameters with Numeric and Vector Layer

On running, the R code in the script will have an object called PointEvents which is a spatial data frame copied from the QGIS layer chosen, with QGIS’ current selection optionally enabled. If you add a line like this to the script:

message("input data has ",nrow(PointEvents)," rows")

you will see how many rows are in the data.

Output Showing Number of Rows

These metadata comments can specify a number of inputs including vector and raster layers, field names from vector layers, bands of a raster, extents and coordinate systems. They can also specify output data where R objects existing at the end of the script become layers in QGIS. The full documentation is on North Road’s github pages site.

At this point we have a working R Processing framework, and we can go on to look at the actual data and do some analysis.

Regional Ratio Analysis

As a next step, we’ll build a script that works out the ratio of events in the two years within each of the London boroughs. The inputs will be a vector layer of points and a vector layer of regions. Start a new model using Create New R Script and add this as the first few lines.

##Point Pattern Analysis=group
##Regional Ratios=name

##Points=vector
##Regions=vector

##R=output vector

That puts the script into a named group with a title of “Regional Ratios”. It will ask for two input layers, both vector data, one will be called Points and one called Regions. At the end of the R code the object called R will be an output and a new layer. The code to go after the comment metadata is this:

library(sf)

# which region (by row) is each point nearest to?
nr = st_nearest_feature(Points, Regions)

# make that into a table with the year
nrt = as.data.frame.matrix(table(nr, Points$Year))

# compute the ratio

r = nrt[["2025"]]/nrt[["2024"]]


# add to the input regions to create the returned object
# with counts and ratio
R = cbind(Regions, nrt)
R$ratio = r

The core of this is using st_nearest_feature to assign a borough to each point, and then table to count points by borough and year. Then there’s some standard R code to add the table of counts and the ratio of 2025:2024 to the regions in an object called R. Save this code and run it from the drop-down menu, under the Point Pattern Analysis group.

Select the thefts for the points, and the boroughs for the regions and run. This should return a new QGIS layer. With some careful styling and labelling you can create a map like this, showing any boroughs that have increased in orange and red, and decreasing boroughs in greens and blues. The labels show the 2025 and 2024 counts.

Borough Increase from 2024 to 2025

This shows a couple of boroughs with more thefts in 2025 than 2024, but most seem to be on a decreasing trajectory. These changes could be within possible statistical noise variation though.

You could make this script more flexible, for example by adding another input to choose which field from the points defines the two categories, then making the R code choose from that column in the input data. Then you could make a map comparing thefts in January with those in June, or in any two groups in any point data set. You could also potentially do all this without R at all, using the standard QGIS processing algorithms and expressions.

In the next example, we’ll make a general script that computes the smoothing of the years directly from the points by computing the ratio of densities.

Density Ratio Analysis

Do thieves respect London borough boundaries? Do they walk past a sign saying “Welcome to Camden” and start stealing bicycles? Probably not, but in the previous analysis we treated the boroughs as a discrete set of spatial units. Sometimes that’s the right thing to do if policy is made at the borough level.

We could use any discrete spatial division and compute the ratio of annual thefts counted in those - for example squares or hexagons - and get a different map. How big should those squares or hexagons be? Too small and we don’t get many points in each one, leading to large uncertainties, and too big and we lose the spatial resolution we want to know about.

A better method is to derive a smooth density surface from each of the point types, and divide one by the other to get a ratio. QGIS can display a density surface from a point layer using its “Heatmap” renderer. This can produce a visually useful impression of point density, especially when points overlap and you cant tell if one marker is one event or twenty three.

Heatmap Rendering of Points

The heatmap renderer has a smoothing control that you adjust until it looks “right”, which might not be the statistically appropriate thing to do. There are methods to choose the amount of smoothing and we can use R to do that. Also, we want to compute a ratio of two of these densities, so we have to go beyond QGIS’ smoothing capabilities.

The R package sparr implements methods for computing the ratio of two classes of events, so we’ll write an R Processing script that uses that.

Inputs and Outputs

What is needed to compute the ratio of two sets of points? We have a points layer with a field called Year that is either 2024 or 2025, and an outline of London as well as a layer of boroughs. For our input we specify a vector layer, a field name from the points layer to split the points on, and a polygon layer for the region to compute the ratio over.

Close any script editor you have open, and create a new script. Adding a group and name specification, this gives us our input section.

##Point Pattern Analysis=group
##Ratio Analysis=name
##Points=vector
##Split=Field Points
##Region=vector

Our output will be the ratio of the two densities over the region, which will be a raster. Output variables are specified in the script using name=output raster where name is the name of the R raster object created by the script to turn into a QGIS raster layer. We’ll be creating an R object called Ratio and that will be our output layer. The output section of our header metadata will look like this.

##Ratio=output raster

Testing I/O Parameters

We can do an initial test on the script so far. If you save the file in the script editor and name it ratio.rsx it should appear in the algorithms menu under the Point Pattern Analysis group.

The Ratio Analysis Icon

If we execute this now (double-click, or right-click and Execute) it will produce a dialog box with the input and output parameters specified. Play with the interface to see how you would select the points, field name, and polygon region as shown here.

Completed Parameter Dialog

Things to note about the inputs:

  • The Points drop-down doesn’t restrict the choice to point geometry objects only. This can be adjusted using the more complex form of parameter specification.
  • The list of fields in the Split drop-down updates when you change the Points layer.
  • Similarly to Points, the Region layer doesn’t restrict the choice to polygon layers, but again this can be done using the complex parameter specification.
  • If you have made a selection in QGIS on an input layer, the Selected features only checkbox will enable. If the algorithm is run with this clicked on then the R code will receive spatial objects with only selected features.
  • The green recycling symbol will run the algorithm once for each feature in the input layer. This could be used, for example, to do independent ratio maps for each borough.
  • The spanner (US: wrench) button lets you apply more complex filters to the input data.
  • The ... button lets you select data that isn’t currently a layer in QGIS, such as from a file on disk or other source.

The output Ratio field by default will write to a temporary file and load into QGIS as a temporary layer, but you can change the output file destination to make it permanent using the button and selecting Save to File...

All that remains once you have set the parameters is to click Run. Except one thing is missing - the R code to do the analysis! You can try clicking Run anyway, and you’ll see an error message since the script doesn’t create an object called Ratio.

R Analysis Code

Writing the actual R code to do the analysis requires a few steps. I’ll show them in parts and then list the full code afterwards.

First we need to add a few packages to our R script before we do anything else. If you’ve not got these packages installed then do that in R with install.packages or a menu item in your IDE.

library(spatstat)
library(sf)
library(sparr)
library(terra)

Convert the Input Data

Since we’re going to use the sparr package to do our ratio, we have to turn our data into somethng sparr can deal with. It builds on spatstat, the spatial point-pattern analysis package of choice, and so we have to convert our points and polygons into spatstat objects.

# convert the region to a spatstat window
w = as.owin(Region)
# convert events to a spatstat ppp
pp = as.ppp(Points)
# set the "marks" according to the split column
marks(pp) = factor(Points[[Split]])
# restrict to the window
pp = pp[w]

Split the Points and Check

Next we need to handle splitting the data into numerator and denominator for the ratio. Since we will probably want the most recent data as the numerator, eg to divide 2025 events by 2024 events to get a measure of increase, we’ll sort the names and later compute the ratio of the second over the first.

The script doesn’t have much checking, but at this point we can test if we have two categories in case the user selected a field that had more, for example if the input had more than two years of data.

# break into a list of two categories
ps = split(pp)
# sort the category values
in_order = sort(names(ps))
# make sure we only have two categories
stopifnot(length(in_order)==2)

Compute the Ratio

Now we can use the risk function to do the hard work. Most of this is boilerplate from the examples in the documentation for risk, and produces reasonable answers, but for full rigour you’d need to understand all the parameters. There’s two steps, first estimate an initial bandwidth and then call risk to do the fitting. Note the order of the first two arguments is set to make sure we divide 2025 events by 2024 events. If the category label values were “A” and “B” then we’d divide “B” events by “A” events. If this wasn’t what the user wanted then they’d have to rename their values, or we could provide an input that flipped the order.

# estimate bandwidth
h0 = sparr::OS(pp, nstar="geometric")

# use the sparr package function for the risk ratio
rr = sparr::risk(
                ps[[in_order[2]]],
                ps[[in_order[1]]],
                h0=h0, adapt=TRUE, tolerate=TRUE,
                hp=OS(pp)/2, pilot.symmetry="pooled",
                davies.baddeley=0.05)

Convert the Output Values

That’s now basically done. Our ratio is in a spatstat raster object in the rr object. We need to get it as a terra spatial raster object called Ratio because that was the name we specified as the output in the initial metadata. Note that the coordinate system hasn’t carried through from the input points to this object, so we need to assign that. We can also set the band name from the category values to give us a meaningful name, like R_2025/2024 for our two-year study or R_case/control if we have case-control data.

Ratio = as(rr$rr,"SpatRaster")
crs(Ratio) = crs(Points)
names(Ratio) = paste0("R_",in_order[2],"/",in_order[1])

Run The Script

The script can now be executed. Choose the bike theft point layer for the Points, set the Year column for splitting and the London boundary layer for the region. After a short computation you should get a new raster layer called Ratio. Notice that the values in this raster are the natural logarithms of the density ratios, and so zero corresponds to no change between 2025 and 2024.

This will initially appear as the default raster style, but you can use QGIS’ symbology to improve that. Select “Singleband pseudocolor” and choose a blue to red colour ramp by reversing the red to blue one. By setting the min and max to appropriate values you can create a colour scheme centred on zero. Using a multiply blending mode you can view the background context map.

Styling a Ratio

We can then make a fair comparison to the borough ratios computed earlier. In QGIS you could open a new map view and use themes to have two differently styled maps on-screen at the same time. This is a direct screengrab from a QGIS session.

Density Smoothing vs Borough Ratios

These don’t seem to be too much in disagreement, although there is a large red area in the south east that is in a borough with a low pale green value in the borough map. What could be happening here is that the smooth density estimate is being biased by small numbers in a rural area, and the extrapolation to red values isn’t statistically significant. The risk function in sparr also returns a significance raster which can be used to test this, but that might be getting too much into the statistics to discuss here.

R Processing Toolbox Thoughts

  • Using the R Processing Toolbox lets you add functionality from R into QGIS
  • Non-R coders can use R models in their own toolchains
  • When developing R Processing tools, the R developer might want to work in their preferred IDE, in which case they should perhaps develop code as an R package. The processing script can then be a simple definition of parameters and a function call.
Analytics by statpx