15  Create

In this guide, we will see how to generate a GeoLocator Data Package from a GeoPressureTemplate folder where you’ve already performed the analysis of the tracks following the GeoPressureTemplate workflow.

Important

To be able to follow this guide, you will need to have a GeoPressureTemplate project containing:

  • An updated the DESCRIPTION file with all relevant information, including version, contributors, licences as described in the R packages book.
  • One interim RData file per tag, with all outputs you would like to publish, generated with the workflow analysis.
  • the tag.csv and observations.csv files in the data/ folder.

If you’ve not yet performed the GeoPressureR analysis, it is still possible to create a geolocator data package with only the core ressources.

For this example, we won’t be using the Swainson’s Warbler nor Great Reed Warbler as we want a full project with multiple tags. Instead, we download the GeoPressureTemplate of the Woodland Kingfisher geolocator project. Our goal will essentially be to reproduce the associated GeoLocator Data Package uploaded on Zenodo already.

We can download this GeoPressureTemplate from Github in a temporary folder using the following code:

repo <- "Rafnuss/WoodlandKingfisher"

# Create temporary file for the ZIP
temp_zip <- tempfile(fileext = ".zip")

# Download the ZIP file and unzip the repository
download.file(
  glue::glue("https://github.com/{repo}/archive/refs/heads/main.zip"),
  temp_zip,
  mode = "wb"
)
temp_dir <- tempfile()
unzip(temp_zip, exdir = temp_dir)

# return the extraction directory
directory <- file.path(temp_dir, list.files(temp_dir))

We can generate a GeoLocator Data Package pkg from a GeoPressureTemplate folder with create_gldp_geopressuretemplate(). This function will read the DESCRIPTION file and create a frictionless package with the metadata. At this stage, no data is included in the package.

pkg <- create_gldp_geopressuretemplate(directory = directory)

Additional metadata can be added or edited.

# There are no embargo by default (1970-01-01)
pkg$embargo <- "2030-01-01"

# If you have a website link, it's quite a nice way to link them up
# pkg$homepage <- ""

# And the url to an image describing your datapackage
# pkg$image <- NULL

# Add keywords
pkg$keywords <- c("Woodland Kingfisher", "intra-african", "multi-sensor geolocator")

# Add DOI of the datapackage if already available or reserve it https://help.zenodo.org/docs/deposit/describe-records/reserve-doi/#reserve-doi
pkg$id <- "https://doi.org/10.5281/zenodo.13829929"

# Provide the recommended citation for the package
pkg$citation <- "Nussbaumer, R., & Rime, Y. (2024). Woodland Kingfisher: Migration route and timing of South African Woodland Kingfisher (v1.1). Zenodo. https://doi.org/10.5281/zenodo.11207141"

# Funding sources
pkg$grants <- c("Swiss Ornithological Intitute")

# Identifiers of resources related to the package (e.g. papers, project pages, derived datasets, APIs, etc.).
pkg$relatedIdentifiers <- list(
  list(
    relationType = "IsPartOf",
    relatedIdentifier = "10.5281/zenodo.11207081",
    relatedIdentifierType = "DOI"
  ),
  list(
    relationType = "IsSupplementTo",
    relatedIdentifier = "",
    relatedIdentifierType = "DOI"
  )
)

# List of references related to the package
# pkg$references <- NULL

Once you’re done, you can visual them

str(pkg[!names(pkg) %in% "resources"])
List of 14
 $ $schema           : 'glue' chr "https://raw.githubusercontent.com/Rafnuss/GeoLocator-DP/main/geolocator-dp-profile.json"
 $ name              : chr "woodlandkingfisher"
 $ licenses          :List of 1
  ..$ :List of 1
  .. ..$ name: chr "CC BY 4.0"
 $ title             : Named chr "Migration route and timing of South African Woodland Kingfisher"
  ..- attr(*, "names")= chr "Title"
 $ version           : chr "1.1"
 $ created           : chr "2024-12-02T09:13:56Z"
 $ embargo           : chr "2030-01-01"
 $ contributors      :List of 2
  ..$ :List of 6
  .. ..$ title     : 'glue' chr "Raphaël Nussbaumer"
  .. ..$ givenName : chr "Raphaël"
  .. ..$ familyName: chr "Nussbaumer"
  .. ..$ roles     : chr [1:2] "Researcher" "ProjectLeader"
  .. ..$ email     : chr "rafnuss@gmail.com"
  .. ..$ path      : 'glue' chr "https://orcid.org/0000-0002-8185-1020"
  ..$ :List of 6
  .. ..$ title     : 'glue' chr "Yann Rime"
  .. ..$ givenName : chr "Yann"
  .. ..$ familyName: chr "Rime"
  .. ..$ roles     : chr [1:2] "Researcher" "Contributor"
  .. ..$ email     : chr "yann.rime@vogelwarte.ch"
  .. ..$ path      : 'glue' chr "https://orcid.org/0009-0005-7264-6753"
 $ directory         : chr "."
 $ keywords          : chr [1:3] "Woodland Kingfisher" "intra-african" "multi-sensor geolocator"
 $ id                : chr "https://doi.org/10.5281/zenodo.13829929"
 $ citation          : chr "Nussbaumer, R., & Rime, Y. (2024). Woodland Kingfisher: Migration route and timing of South African Woodland Ki"| __truncated__
 $ grants            : chr "Swiss Ornithological Intitute"
 $ relatedIdentifiers:List of 2
  ..$ :List of 3
  .. ..$ relationType         : chr "IsPartOf"
  .. ..$ relatedIdentifier    : chr "10.5281/zenodo.11207081"
  .. ..$ relatedIdentifierType: chr "DOI"
  ..$ :List of 3
  .. ..$ relationType         : chr "IsSupplementTo"
  .. ..$ relatedIdentifier    : chr ""
  .. ..$ relatedIdentifierType: chr "DOI"

You can also export these metadata as datapackage.json with:

package_json <- jsonlite::toJSON(pkg, pretty = TRUE, null = "null", na = "null", auto_unbox = TRUE)
write(package_json, "datapackage.json")

15.1 Add the tag data

Once we have created the package, we can add the data to the package from the interim .RData files.

pkg <- pkg %>%
  add_gldp_geopressuretemplate(directory = directory, from = "interim")
print(pkg)
A GeoLocator Data Package with 8 resourcess:
• tags
• observations
• measurements
• twilights
• staps
• paths
• edges
• pressurepaths
Use `unclass()` to print the Data Package as a list.

If you haven’t performed the GeoPressureR analysis yet, but still want to create a GeoLocator Data Package, you can use the add_gldp_geopressuretempate() with from="raw-tag", which will read the data from directly “./data/raw-tag/”.

pkg <- pkg %>%
  add_gldp_geopressuretemplate(directory = directory, from = "raw-tag")

15.2 Update tags and observations tables

In the ideal case, tags.csv and observations.csv have been returned by the ringer. In this case, you can simply replace them with:

tags(pkg) <- read_csv("data/tags.csv") # or read_xlsx()
observations(pkg) <- read_csv("data/observations.csv")

Alternatively, you might want to start from the table created from the information available in the GeoPressureTemplate folder and edit the tables manually. I suggest creating a temporary .xlsx spreadsheet (and not .csv to preserve the column class), modify it in Excel, and read it back into R. You can also edit the table directly with dplyr functions.

temp_file <- tempfile(fileext = ".xlsx")
write_xlsx(tags(pkg), temp_file)
system(paste("open", temp_file))
# Edit it on the external program and once you're done, save you file and update the table
tags(pkg) <- read_xlsx(temp_file)
Warning

Don’t forget to update the metadata of your Data Package when you have updated a table.

pkg <- update_gldp(pkg)

15.3 Check the validity of the data package

You can visualize the coverage of the package by ploting the Data Package. Check for the correct number of tags, as well as equipment and retrieval dates.

plot(pkg)

Finally, we check that the package is compliant with GeoLocator Data Package standards.

15.4 Write the package and upload to Zenodo

Now that the package is ready, we can write it to disk.

write_package(pkg, file.path("~/", pkg$name))

The folder created contains all the resources needed for your GeoLocator-DP. Simply upload them to your Zenodo! Use the information in datapackage.json to fill the Zenodo form.