Worked example

2025-10-29

This worked example describes the use of spmapper and its core functions.

Install spmapper

You can install spmapper directly from within R (recommended) with the below code, or via download from the github repository, linked via the “Download spmapper” box on the homepage of this website.

# Install spmapper from within R 
library(devtools)
devtools::install_github("NERC-CEH/spmapper-pkg") 

## If you have downloaded the package files directly from the github repository,  you will first need to install the package by modifying the below example code
# install.packages("C:/Users/myusername/Downloads/spmapper-pkg_[0.1.0].tar.gz", repos = NULL, type = "source") # with the correct file path and version name etc

# load the package
library(spmapper) 

Load packages and functions

Load packages needed for tool functions. Check you have all necessary packages installed.

# load required packages
library(spmapper)
library(terra) 
library(sf)
library(knitr)
library(rnaturalearth)
library(viridis)
library(ggplot2)
library(patchwork)

Define tool directory path - this is important to source the package functions, and for those functions to locate the input data!

## Define tool directory path
tooldir <- system.file("extdata", package = "spmapper") # automatically find and define your file path - but do check the path is correct

# tooldir <- file.path(".../spmapper") # alternatively, modify here to your package files directory if you have installed the package elsewhere

# Load package functions
invisible(system.file("R", "functions_preymodel.R", package = "spmapper"))
invisible(system.file("R", "functions_spmapper.R", package = "spmapper"))
invisible(system.file("R", "functions_fpudoverlap.R", package = "spmapper"))
invisible(system.file("R", "functions_spmapplot.R", package = "spmapper"))

Worked example

Specify user polygon(s)

Users can specify multiple polygon/multipolygon objects and apply the rest of the example code to compare prey consumption across areas. spmapper functions are capable of handling multipolygon objects. Users are reminded to define the Coordinate Reference System (CRS) of their loaded shapefiles. spmapper reprojects user polygons to align to the prey consumption maps. spmapper includes a function to plot prey consumption maps with the user polygons overlaid (see below).

# Specify shapefile/s
fppolys <- sf::st_read(file.path()) # Add your filepath/s here. 

## Users must define the CRS of their loaded shapefile for spmapper to function!
fppolys <- st_crs([...]) # define source file CRS

Example data presented

UK offshore wind farm footprints of ‘production’, ‘planned’, ‘construction’ and ‘approved’ statuses, collated for the European Marine Observation and Data Network (via EMODnet; CETMAR, 2024). Offshore electricity transmission (OFTO) polygons excluded.

Run primary function spmapper() - produces prey consumption maps for all species and optionally extracts quantities within user-specified polygons, if provided.

Optionally specify polygons with “fppolys =”. Users must specify the directory to tool data with “tooldir =” (defined earlier under ‘Load packages and functions’). The object returned (assigned as the object named ‘out’ in this example) is a list object. This list contains 3 sub-lists (one per species) of the various inputs, quantities, and output prey consumption maps and extracted quantities. The species sub-lists are named by species, e.g. ‘out$Kittiwake’. The spmapper() output list also contains a dataframe summary of key results per species (named ‘Summary’, retrieved via ‘out$Summary’). The spmapper() function provides updates on its progress through the calculations.

out <- spmapper(fppolys = fppolys, tooldir = tooldir)

## |---------|---------|---------|---------|=========================================                                          

## [1] "Completed 1 of 3 species: Kittiwake"
## |---------|---------|---------|---------|=========================================                                          

## [1] "Completed 2 of 3 species: Guillemot"
## |---------|---------|---------|---------|=========================================                                          

## [1] "Completed 3 of 3 species: Razorbill"

Note, if you pass spmapper() a set of multiple polygons (i.e. a multipolygon object), spatial extractions will be performed and summed across all contained polygons. If you are interested in comparing two specific polygons - or two sets of polygons - you will need to run spmapper() separately for each, and then compare results. See example code below to run the tool for two individual or sets of input polygons, ‘fppolys1’ and ‘fppolys2’.

out1 <- spmapper(fppolys = fppolys1, tooldir = tooldir)
out2 <- spmapper(fppolys = fppolys2, tooldir = tooldir)

Visualise prey consumption maps with optional input polygons overlaid, using spmapplot()

spmapplot() takes two arguments, the first is a prey consumption map (raster, generated by spmapper(), contained in list outputs in the form out_kitt$prey_cons_map), the second optional argument is a polygon object (e.g. the user’s polygons, fppolys)

# Plot all species prey consumption maps 
(spmapplot(out$Kittiwake$prey_cons_map, fppolys) + ggtitle("Kittiwake")) +
(spmapplot(out$Guillemot$prey_cons_map, fppolys) + ggtitle("Guillemot")) +
(spmapplot(out$Razorbill$prey_cons_map, fppolys) + ggtitle("Razorbill")) + 
  patchwork::plot_layout(ncol = 1)

# Or plot a single species map, e.g. Razorbill
spmapplot(out$Razorbill$prey_cons_map, fppolys) + ggtitle("Razorbill")

Visualise prey mass estimates

The following code plots the distribution of prey mass estimates produced by spmapper(), and annotates the baseline estimate with a dashed line.

blki_p <- ggplot(data.frame(out$Kittiwake$allbirds_prey_sim), aes(out$Kittiwake$allbirds_prey_sim/1000)) +
  geom_histogram(bins = 50, color = "gray10", fill = "skyblue") +
  geom_vline(xintercept = out$Kittiwake$allbirds_prey_est/1000, color = "gray10", linetype = "longdash", linewidth = 1.1) +
  labs(x = "Prey consumption mass, t", y = "Frequency", title = "Kittiwake") +
  theme_minimal()

cogu_p <- ggplot(data.frame(out$Guillemot$allbirds_prey_sim), aes(out$Guillemot$allbirds_prey_sim/1000)) +
  geom_histogram(bins = 50, color = "gray10", fill = "skyblue") +
  geom_vline(xintercept = out$Guillemot$allbirds_prey_est/1000, color = "gray10", linetype = "longdash", linewidth = 1.1) +
  labs(x = "Prey consumption mass, t", y = "Frequency", title = "Guillemot") +
  theme_minimal()

razo_p <- ggplot(data.frame(out$Razorbill$allbirds_prey_sim), aes(out$Razorbill$allbirds_prey_sim/1000)) +
  geom_histogram(bins = 50, color = "gray10", fill = "skyblue") +
  geom_vline(xintercept = out$Razorbill$allbirds_prey_est/1000, color = "gray10", linetype = "longdash", linewidth = 1.1) +
  labs(x = "Prey consumption mass, t", y = "Frequency", title = "Razorbill") +
  theme_minimal()

(blki_p + cogu_p + razo_p) 

View key results

The following code retrieves a table of prey mass consumption (kg) estimates for each species and the results of the spatial extraction of prey consumption within polygons. Users can also access the full input/output data per species within the output sub-list for each (e.g. via ‘out$Kittiwake’, and the entries therein).

Estimate_kg refers to the baseline total prey consumption (kg) estimate; CI_Lower_kg and CI_Upper_kg refer to the lower (2.5%) and upper (97.5%) confidence intervals, respectively.

fp_percent is the percentage of total prey consumption contained within the polygons. fp_Estimate_kg is the baseline prey mass (kg) contained within the polygons; fp_CI_Lower_kg and fp_CI_Upper_kg refer to the lower (2.5%) and upper (97.5%) confidence intervals, respectively.

out$Summary

spmapper Key Results

Species	Estimate_kg	CI_Lower_kg	CI_Upper_kg	fp_percent	fp_Estimate_kg	fp_CI_Lower_kg	fp_CI_Upper_kg
Kittiwake	4819894.3	4085681.9	5718792	6.99	336915.8	285593.59	399749.74
Guillemot	5681001.3	4775665.0	9955648	4.28	243174.5	204421.73	426150.25
Razorbill	718604.3	553496.9	1122483	3.24	23257.7	17913.99	36329.28

---

Mis-specification of inputs

spmapper performs checks for potential input specification errors. The following examples illustrate the error messages produced under cases of mis-specification.

Incorrect path to tool

spmapper* does not currently explicitly check if the path provided is correct/valid, but may yield sensible error messages if an incorrect path is specified.

spmapper(fppolys = fppolys, tooldir = "test")

## Warning in file(file, "rt"): cannot open file 'test/fame_population_ests.csv':
## No such file or directory

## Error in file(file, "rt"): cannot open the connection

Validity of footprints

The tool does not check directly for the validity of the polygons provided, but does run three checks for consistency between polygons and the prey consumption maps. spmapplot() can be used to visualise polygons overlaid on the prey consumption maps.

1. Footprints on land (or in other areas of map without values)

## |---------|---------|---------|---------|=========================================                                          

## Error in fpudoverlap(fppolys = fppolys, udmap = udmap): Zero overlap between footprint and any grid cell

2. Footprints smaller than one grid cell

## Error in fpudoverlap(fppolys = fppolys, udmap = udmap): Size of footprint is smaller than the size of a single grid cell - tool would not produce meaningful results in this situation

3. Footprints outside extent of prey consumption maps

Note: this may be footprints on land, but it could also be footprints in areas that are within extent but in areas that weren’t included in the original modelling in Wakefield et al. (2017).

## Error in fpudoverlap(fppolys = fppolys, udmap = udmap): Polygon lies partly or completely outside area of selected grid!