9  Introduction

GeoPressureTemplate is a Github repository template which contains a standard folder structure and R scripts to store your data, analyse it, and produce trajectory outputs. Download it as a starting point to organise your data and start your analysis. It’s an initial flexible structure that should be adapted to each individual project.

9.1 📁 Project structure

GeoPressureTemplate defines a standardized project folder structure based on a mix of rrrpkg, rrtools and cookiecutter data science.

GeoPressureTemplate/
├── DESCRIPTION                             # Project metadata and dependencies
├── README.md                               # Top-level description of content and guide to users
├── GeoPressureTemplate.Rproj               # R project file
├── LICENCES.md                             # Conditions of re/use the data and code
├── config.yml                              # YML file used to defined the parameters used in the analysis
├── data/                                 
│   ├── raw_tag/                            # Raw geolocator data (do not modify!)
│   │   ├── 18LX/
│   │   │   ├── 18LX_20180725.acceleration
│   │   │   ├── 18LX_20180725.glf
│   │   │   └── 18LX_20180725.pressure 
│   │   └── CB619/ 
│   │       └── CB619.deg
│   ├── tag_label/                          # Trainset csv file generated with analyis/1-label.qmd
│   │   ├── 18LX-labeled.csv
│   │   ├── 18LX.csv 
│   │   ├── CB619-labeled.csv
│   │   └── CB619.csv            
│   ├── twilight_label/                     # Trainset csv file generated with analyis/2-twilight.qmd
│   │   ├── 18LX-labeled.csv
│   │   └── 18LX.csv
│   ├── wind/                               # ERA-5 wind data generated with analyis/3-wind.qmd
│   │   └── 18LX/
│   │       ├── 18LX_1.nc
│   │       └── ...
│   └── interim/                            # Intermediate data created with analyis/4-geopressuretemplate.R
│       └── 18LX.RData                      
├── analysis/                               # R script used to analyse your data.
│   ├── 1-label.qmd
│   ├── 2-twilight.qmd
│   ├── 3-wind.qmd
│   ├── 4-geopressuretemplate.R
│   ├── 5-datapackage.R
│   └── 12-label-advanced.qmd
├── R/                                      # Custom R functions used in your analysis.
└── output/   
    ├── create_figures.R
    └── figures/

9.2 💡 Get started

9.2.1 🛠️ Create your project

Option 1: with a Github repository (recommended)

  • Open GeoPressureTemplate and click on the green button “Use this template” or click here to create your repository directly.
  • Choose a project name (e.g., my_tracking_study_name) specific to your research. Note that this will become the name of your folder on your computer too.
  • Clone the repository on your computer.
  • Done! 🎉

Option 2: without a Github repository

  • Click here to download the repo directly
  • Unzip and rename the folder with your project name.
  • Done! 🎉
Important

Do not clone (or fork) the repository! Read more about creating repositories from a template.

9.2.2 🏠 Make yourself at home

  1. Rename GeoPressureTemplate.Rproj to your project name (e.g., my_tracking_study_name.Rproj). You can now open the project on RStudio.
  2. Edit the DESCRIPTION file following the R package book.
  3. Add your research description in the README.md, including your research objectives, basic data, and method.
  4. Replace the content of data/ with your tag data.
  5. Install the dependencies needed with
devtools::install()
  1. Optionally, modify the LICENCES file (see the R package book for details).

9.3 💫 How to master config.yml ?

Before jumping into the analysis, we need to introduce config.yml. It’s a YAML file which defines the parameters used in the analysis. Separating these parameters from the main code follows best practices in terms of reproducibility, readability, and sharability. We use the config R package to retrieve all the parameter values used in the code.

Note

An important benefit of config is its ability to manage hierarchical configurations: you can organize settings into different groups and override them as needed. This is particularly useful in our context, where we can configure parameters for all tags and/or specific tags.

default:
  tag_create:
    extent: [-16, 23, 0, 50] # [W, E, S, N]
    scale: 1

18LX:
  tag_set_map:
    scale: 5
config::get("tag_create", "18LX")$extent
# [-16, 23, 0, 50] # Returns the default value if not set in 18LX
config::get("tag_set_map", "18LX")$scale
# 5 # Return the value in 18LX if presents in both

9.4 📈 Analyse the data

Now that you’re set up, it’s time to get serious 😬.

9.4.1 Step 1: Preparation

Here we make sure everything is ready to run the model. This mainly involves defining the parameters in config.yml by running the following three scripts:

  1. Run analysis/1-label.qmd.
  2. Run analysis/2-twilight.qmd, if you have light data.
  3. Run analysis/3-wind.qmd, if you want to account for wind.

You can visualize each of scripts in a nice-to-read HTML format, using the example of 16LX, in the next sections of this manual.

Note

When running the scripts, please keep in mind:

  • Nothing is saved at the end of these scripts (and that’s how it’s supposed to be!). Only label files and config.yml should be edited.
  • The scripts should be run for each tag separately.
  • We use Quarto to make it easy to run chunks based on your needs (e.g., re-run a small chunk after making a change). The scripts are not meant to be run with Run all.
  • These scripts can (and should) be edited based on your prefered workflow.
Tip

For regular users, we provide a shorter version of these preparation steps in analysis/12-label-advanced.qmd.

9.4.2 Step 2: Run GeoPressureR workflow

Caution

The core benefit of using GeoPressureTemplate is coming now! You can finally gain back all the time you’ve invested in setting up this project folder! Keep reading carefully!

The geopressuretemplate() function allows you to run the entire GeoPressureR workflow with a single function. By using this workflow, you make sure that your work is reproducible.

geopressuretemplate("18LX")

This will create data/interim/18LX.RData with all the trajectory outputs. You’ll learn more in the Workflow chapter. In GeoPressureTemplate, this is performed in the file analysis/4-geopressuretemplate.R.

9.4.3 Step 3: Your own analysis

You’ve reached the final steps of GeoPressureTemplate, but this is only the beginning of your research journey. You now have the bird trajectories, but the real magic happens when you apply your creativity and insights to analyse these! You can continue using GeoPressureTemplate, adding other sources of data and analysis to answer your research question.

9.5 🗞️ Publication

For peer-review publication, it is essential that the data and code are accessible to reviewers. Because inaccurate labelling can lead to wrong trajectory, we highly encourage you to publish your data and code.

9.5.1 GeoPressureTemplate Code

Simply publish your GeoPressureTemplate Github repository on Zenodo following this guide. Publishing on Zenodo will generate a DOI for your code.

9.5.2 Geolocator Data Package

While publishing your GeoPressureTemplate on Zenodo is a great step to allow others to see (and, if needed, reproduce) your work, it can be challenge to re-use your track data for other purposes. To facilitate this, we created GeoLocator Data Package, a data exchange format for geolocator data, providing all GeoPressureR outputs in csv files. The aim of GeoLocator DP is re-usability rather than reproduction.

This step is performed with the script analysis/5-datapackage.R. To learn more about publishing a GeoLocator Data Package, go to GeoLocatoR DP.

9.6 🔗 Advanced options