15  Reuse a study

A published GeoLocator Data Package contains everything a study produced: the tags, the raw measurements, the labels and the trajectories of all its birds. This chapter shows how to find a package, read it, join its tables, and bring a tag back into GeoPressureR. We use the South African Woodland Kingfisher study as an example. To compare many studies, see Compare studies with the Master.

library(GeoLocatoR)
library(GeoPressureR)
library(tidyverse)
theme_set(theme_minimal(base_size = 12) + theme(panel.grid.minor = element_blank()))

15.1 Find a dataset

Browse published packages with the GeoLocatorExplorer, or directly in the geolocator-dp Zenodo community.

Screenshot of GeoLocatorExplorer showing searchable geolocator data packages

GeoLocatorExplorer interface to browse published geolocator data packages.

15.2 Read a package

read_zenodo() takes a Zenodo record id, a DOI or a Zenodo URL. It downloads the files, upgrades the package to the latest GeoLocator DP version if needed, and returns a geolocatordp object.

pkg <- read_zenodo("13829929")

A record id or DOI can be a version (one fixed release) or a concept (all versions, resolving to the latest). 13829929 is the concept id of this study, so pkg$id gives the version actually read: keep it with your results. read_zenodo() downloads every table of the package, including the raw measurements. To read only some tables, see Read only the tables you need.

print(pkg)
## 
## ── A GeoLocator Data Package `pkg` (v1.2) ──────────────────────────────────────
## 
## ── Metadata
## Note: All green texts are fields of `pkg` which can be accessed with
## `pkg$field`.
## • title: "GeoLocator Data Package: South African Woodland Kingfisher"
## • id: <https://doi.org/10.5281/zenodo.15259676>
## • contributors:
##   Raphaël Nussbaumer (contactperson) - <https://orcid.org/0000-0002-8185-1020>
##   Yann Rime (researcher) - <https://orcid.org/0009-0005-7264-6753>
##   Samuel Temidayo Osinubi (datacollector) -
##   <https://orcid.org/0000-0002-5143-6985>
## ✔ access: Open access
## • licenses: Creative Commons Attribution 4.0 International (cc-by-4.0) -
##   <https://creativecommons.org/licenses/by/4.0/legalcode>
## • description: "This repository contains the raw data and the trajectory
##   information generated with the GeoPressureR workflow, following the
##   GeoLocator Data Package standard. The more complete code used to generate
##   this datapackage can be found on the Github Reposit..."
## • version: "v1.2.1"
## • codeRepository: <https://github.com/Rafnuss/WoodlandKingfisher>
## ✔ community: Geolocator DP community
## • relatedIdentifiers:
##   issupplementto <https://doi.org/10.1098/rspb.2024.2633>
## • keywords: "Woodland Kingfisher", "multi-sensor geolocator", "intra-african
##   migration", "bird", and "migration"
## • created: 2025-04-22 06:44:20.918179
## • bibliographicCitation: "Nussbaumer R, Rime Y, Osinubi S (2025). \"GeoLocator
##   Data Package: South African Woodland Kingfisher.\"
##   doi:10.5281/zenodo.13829929 <https://doi.org/10.5281/zenodo.13829929>.
##   <https://zenodo.org/records/15259676>."
## • temporal: "2017-01-10" to "2019-09-28"
## • taxonomic: "Halcyon senegalensis"
## • numberTags: tags: 25, measurements: 5, light: 5, pressure: 5, activity: 5,
##   temperature_external: 5, magnetic: 5, paths: 5, pressurepaths: 5
## 
## ── Resources: (8 resources)
## • `tags()` (n=25)
## • `observations()` (n=64)
## • `measurements()` (n=1,924,975)
## • `staps()` (n=223)
## • `twilights()` (n=3,262)
## • `paths()` (n=22,523)
## • `edges()` (n=22,018)
## • `pressurepaths()` (n=224,828)
plot(pkg, "map")

Each table has an accessor returning a tibble: tags(), observations(), measurements(), staps(), paths(), edges(), twilights() and pressurepaths(). Their content is described in Publish your data and on the GeoLocator DP website.

15.3 Keys and joins

The tables of a package are linked by keys, like a relational database. The schema overview draws them all.

  • A primary key identifies each row. In staps, it is the pair tag_id and stap_id: stationary period 3 only means something for a given tag.
  • A foreign key points to the primary key of another table. paths and edges point to staps, and all tables point to tags through tag_id.

The trajectory tables add two columns to their primary key:

Table Primary key
paths tag_id, type, j, stap_id
edges tag_id, type, j, stap_s
pressurepaths tag_id, type, j, datetime

type is most_likely, the single best trajectory (j = 1); simulation, random draws from the posterior distribution (j = 1 to nj) that carry the location uncertainty; geopressureviz, a path edited by hand in geopressureviz(); or tag, the most likely position of each stationary period taken separately from its likelihood map, without the movement model. Always join trajectory tables on type and j, or you will mix trajectories.

In dplyr, a join takes the keys in by. When the columns have different names, join_by() maps them. For example, to get the position where each flight started, join edges to paths on the departure stationary period stap_s:

edges(pkg) |>
  left_join(paths(pkg), by = join_by(tag_id, type, j, stap_s == stap_id)) |>
  select(tag_id, type, j, stap_s, stap_t, lat, lon, distance) |>
  head() |>
  knitr::kable(digits = 1)
tag_id type j stap_s stap_t lat lon distance
16LN most_likely 1 1 2 -22.7 28.8 363.6
16LN most_likely 1 2 3 -20.1 26.6 140.8
16LN most_likely 1 3 4 -18.9 26.4 114.7
16LN most_likely 1 4 5 -18.1 27.1 122.7
16LN most_likely 1 5 6 -17.1 26.6 79.8
16LN most_likely 1 6 7 -17.1 27.4 250.0

The same keys tell you how to aggregate. The total distance flown is a sum over the flights of one trajectory, so we group by tag_id, type and j, then summarise the simulations of each tag:

edges(pkg) |>
  summarise(km = sum(distance), .by = c(tag_id, type, j)) |>
  summarise(
    most_likely = km[type == "most_likely"],
    median = median(km[type == "simulation"]),
    lower = quantile(km[type == "simulation"], 0.05),
    upper = quantile(km[type == "simulation"], 0.95),
    .by = tag_id
  ) |>
  knitr::kable(digits = 0, col.names = c("Tag", "Most likely (km)", "Simulations (km)", "5%", "95%"))
Tag Most likely (km) Simulations (km) 5% 95%
16LN 8243 9643 9094 10346
16LO 8813 9900 9225 10611
16LP 7794 9033 8463 9770
20IK 8465 10336 9711 10906
22NO 4393 5129 4780 5631

The most likely trajectory is shorter than every simulation: it is the best position at each stationary period, so it smooths out the zig-zags that the simulations draw within the location uncertainty. Use the simulations for quantities summed along a trajectory.

15.4 Compare the birds of a study

Because all tags share the same tables, figures across birds are a few joins away. Here, the latitude of each bird through the year, expanded to one value per day from its stationary periods, with the 90% interval of the simulations:

latitude <- paths(pkg) |>
  summarise(
    lower = quantile(lat[type == "simulation"], 0.05),
    upper = quantile(lat[type == "simulation"], 0.95),
    lat = lat[type == "most_likely"],
    .by = c(tag_id, stap_id)
  ) |>
  inner_join(staps(pkg), by = c("tag_id", "stap_id")) |>
  reframe(
    date = seq(as.Date(start), as.Date(end), by = "day"),
    .by = c(tag_id, stap_id, lat, lower, upper)
  ) |>
  distinct(tag_id, date, .keep_all = TRUE)
Code
latitude |>
  mutate(doy = yday(date), year = year(date)) |>
  ggplot(aes(doy, group = interaction(tag_id, year), colour = tag_id, fill = tag_id)) +
  geom_hline(yintercept = 0, colour = "grey60", linetype = "dashed") +
  geom_ribbon(aes(ymin = lower, ymax = upper), alpha = 0.15, colour = NA) +
  geom_line(aes(y = lat), linewidth = 0.8) +
  scale_x_continuous(
    breaks = c(1, 32, 60, 91, 121, 152, 182, 213, 244, 274, 305, 335),
    labels = month.abb, expand = expansion(mult = 0.01)
  ) +
  scale_colour_brewer(palette = "Dark2", aesthetics = c("colour", "fill")) +
  labs(
    x = NULL, y = "Latitude", colour = "Tag", fill = "Tag",
    title = "Woodland Kingfishers spend the austral winter north of the equator"
  ) +
  theme(legend.position = "bottom", plot.title.position = "plot", plot.title = element_text(face = "bold"))

All five birds leave South Africa between late March and mid-April, spend the austral winter around 8–11°N, and are back by early December.

15.5 Back to GeoPressureR

A package keeps the raw measurements and the labels of the original analysis. gldp_to_tag() converts them into a GeoPressureR tag object, with its labelled pressure, its stationary periods and its twilights:

tag <- gldp_to_tag(pkg, tag_id = "16LP")
tag

From here, the tag works with every chapter of this manual. For instance, you can recompute its pressure map with different settings, add a light map, or build a trajectory with wind. Without tag_id, gldp_to_tag() returns a named list with one tag per bird.

To re-run the whole study, create_geopressuretemplate() creates a GeoPressureTemplate project with the data, labels and parameters of all tags:

create_geopressuretemplate(path = "~/woodlandkingfisher", pkg = pkg)

15.6 Licence, embargo and contact

pkg$licenses gives the licence and pkg$bibliographicCitation the citation, with the concept DOI: cite it, and record the version you used (pkg$id, e.g. in your methods). Also cite the paper describing GeoLocator DP, Nussbaumer et al. (2026). Read the record’s description too: authors often ask to be contacted, and they know the caveats of their data. pkg$contributors lists their roles: write to the contact person. An embargoed record has public metadata but no files: read_zenodo() warns and returns the metadata only. Ask its authors for access, and do not redistribute data obtained this way.

15.7 Compare studies

To compare studies, do not download and merge packages yourself: the Master GeoLocator Data Package already compiles them all into one versioned dataset. See Compare studies with the Master.