Spatial filtering

Contextual and spatial layers

Often we want to filter results down to some commonly defined spatial regions, such as states, LGAs or IBRA/IMCRA regions. The ALA contains a large range (>100) of contextual and spatial layers, in-built as searchable and queriable fields. They are denoted by names beginning with "cl", followed by an identifying number that may be up to 6 digits long. These fields are each based on shapefiles, and contain the names of the regions in these layers that each record lies in.

We strongly recommend using search_fields() to check whether a contextual layer already exists in the ALA that matches what you require before proceeding with other methods of spatial filtering. These fields are all able to be queried with filter()and so they are generally easier to use.

Suppose we are interested in querying records of the Red-Necked Avocet (Recurvirostra novaehollandiae) in a particular protected wetlands, the Coorong wetlands in South Australia. We can search the ALA fields for wetlands.

library(galah)
library(tidyverse)
library(gt)
library(sf)

galah_config(email = "your_email_here", verbose = FALSE)

search_fields("wetlands")

## # A tibble: 1 × 3
##   id    description                     type  
##   <chr> <chr>                           <chr> 
## 1 cl901 Directory of Important Wetlands fields

Our search identifies that layer cl901 seems to match what we are looking for. We can then either view all possible values in the field with show_values(), or search again for our particular field.

search_fields("cl901") |> search_values("coorong")

## • Showing values for 'cl901'.

## # A tibble: 1 × 1
##   cl901                                      
##   <chr>                                      
## 1 The Coorong, Lake Alexandrina & Lake Albert

We can filter all occurrences for exact matches with this value, "Lake Eyre". Our galah query can be built as follows:

galah_call() |>
  identify("Recurvirostra novaehollandiae") |>
  filter(cl901 == "The Coorong, Lake Alexandrina & Lake Albert") |>
  collect() |>
  head(5) |>
  gt::gt()

galah_geolocate()

While server-side spatial information is useful, there are likely to be cases where the shapefile or region you wish to query will not be pre-loaded as a contextual layer in the ALA. In this case, shapefiles can be introduced to the filtering process using the {sf} package and the galah_geolocate() function. Shapefiles can be provided as an sf object, whether that is by importing them with sf::st_read() or taking a POLYGON or MULTIPOLYGON character string and transforming them with sf::st_as_sfc().

For instance, we might interested in species occurrences in King George Square, Brisbane. We can take the MULTIPOLYGON object for the square (as sourced from the Brisbane City Council) and transform it into sfc and then sf objects.

king_george_sq <- "MULTIPOLYGON(((153.0243 -27.46886, 153.0242 -27.46896, 153.0236 -27.46837, 153.0239 -27.46814, 153.0239 -27.46813, 153.0242 -27.46789, 153.0244 -27.46805, 153.0245 -27.46821, 153.0246 -27.46828, 153.0247 -27.46835, 153.0248 -27.46848, 153.0246 -27.4686, 153.0246 -27.46862, 153.0245 -27.46871, 153.0243 -27.46886)))" |>
  sf::st_as_sfc() |> 
  sf::st_as_sf()

We can provide this MULTIPOLYGON in our filter as the argument of galah_geolocate() to assess which species have been recorded in King George Square.

galah_call() |>
  galah_geolocate(king_george_sq) |>
  select(decimalLatitude, 
         decimalLongitude, 
         eventDate, 
         scientificName, 
         vernacularName) |>
  collect() |> 
  head(10) |>
  gt::gt()

There is a second argument of galah_geolocate() called type, which defaults to value "polygon". By setting the type argument to "bbox", the provided POLYGON or MULTIPOLYGON will be converted into the smallest bounding box (rectangle) that contains the POLYGON. In this case, records will be included that may not exactly lie inside the provided shape.

galah_call() |>
  galah_geolocate(king_george_sq, type = "bbox") |>
  select(decimalLatitude, 
         decimalLongitude, 
         eventDate, 
         scientificName, 
         vernacularName) |>
  collect() |>
  head(10) |>
  gt::gt()

## Data returned for bounding box:
## xmin = 153.0236 xmax = 153.0248 ymin = -27.46896 ymax = -27.46789

brisbane_parks <- sf::st_read("path/to/Park___Locations.shp") |>
  sf::st_make_valid() |>
  filter(POST_CODE == 4075)

# Convert shapefile to a bounding box
brisbane_parks_bbox <- brisbane_parks |> sf::st_bbox()

# Find all occurrences of Trichoglossus chlorolepidotus in the bounding box in 2022
lorikeet_brisbane <- galah_call() |>
  filter(scientificName == "Trichoglossus chlorolepidotus", 
         year >= 2020) |>
  galah_geolocate(brisbane_parks_bbox, type = "bbox") |>
  collect()

## Data returned for bounding box:
## xmin = 152.96331 xmax = 152.99668 ymin = -27.57737 ymax = -27.51606

# Filter records down to only those in the shapefile polygons
lorikeet_brisbane |>
  # Create a point geometry based on the occurrence coordinates
  sf::st_as_sf(coords = c("decimalLongitude", "decimalLatitude"), crs = sf::st_crs(brisbane_parks), remove = FALSE) |>
  # identify which park each occurrence sits in with st_intersects()
  mutate(intersection = sf::st_intersects(geometry, brisbane_parks) |> as.integer(),
         park = ifelse(is.na(intersection), NA, brisbane_parks$PARK_NAME[intersection])) |>
  # Filter out occurrences that did not occur in a park
  filter(!is.na(park)) |>
  # Drop the geometry column
  sf::st_drop_geometry() |>
  # Summarise the top 10 parks for lorikeet sightings in 2022
  group_by(park) |>
  summarise(counts = n()) |>
  arrange(desc(counts)) |>
  head(10)

## # A tibble: 10 × 2
##    park                           counts
##    <chr>                           <int>
##  1 SHERWOOD ARBORETUM                276
##  2 NYUNDARE-BA PARK                  271
##  3 FAULKNER PARK                      51
##  4 STRICKLAND TERRACE PARK            33
##  5 FORT ROAD BUSHLAND                 31
##  6 GRACEVILLE RIVERSIDE PARKLANDS     31
##  7 BENARRAWA RESERVE                  19
##  8 NOSWORTHY PARK                     16
##  9 HORACE WINDOW RESERVE               9
## 10 GRACEVILLE AVENUE PARK              6