Analyzing geolocator data with GeoPressureR is full of potential, but the the path is long and the journey can be challenging. GeoPressureTemplate
provides a start-up R project to make that journey easier.
This Github repository template contains a standard project folder structure and R script to store your data, analyse it, and produce outputs.
We defined 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, typically .RData or .Rds
โ โโโ 18LX.RData
โโโ analysis/ # R code used to analyse your data.
โ โโโ 1-label.qmd
โ โโโ 2-twilight.qmd
โ โโโ 3-wind.qmd
โ โโโ 4-geopressure.R
โโโ output/
โโโ create_figures.R
โโโ figures/
Option 1: with a Github repository (recommended)
- Create your project repo by clicking on the green button "Use this template".
- 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
- Download the repo by clicking on the green button Code and Download ZIP
- Unzip and rename the folder name to your own project name.
- Done! ๐
- Rename
GeoPressureTemplate.Rproj
to your study name (e.g.,my_tracking_study_name.Rproj
). You can now open the project on RStudio. - Edit the
DESCRIPTION
file (see https://r-pkgs.org/description.html for details). - Delete the content of
README.md
and write your research objectives, describing your basic data, method etc. - Replace the content of
data/
with your tag data. - Install the dependencies needed with
devtools::install()
- Optionally, modify the
LICENCES.md
file (see https://r-pkgs.org/license.html for details).
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 the parameter values in the code with,
config::get("crop_start", config = "18LX") # "2017-06-20"
One advantage of this file is the ability to define a default set of parameters (i.e. valid for all tags), as well as specific parameters for each tag.
config::get("thr_gs", config = "18LX") # 150
Now that you are set up, it's time to get serious ๐ฌ
In this first step, we will make sure everything is ready to run the model. This involves setting up the parameters in config.yml
while running the following three scripts:
- Run
1-label.qmd
- (optional)
2-twilight.qmd
- (optional)
3-wind.qmd
While doing so, please keep in mind: - Nothing is saved at the end of the script (and that's how it's supposed to be!). Only label files and config.yml
should be edited. - The scripts should be run successively for each tag separately - We use quarto script 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 should be adapted based on your project, but the same script should run for all your tags.
The main script is 4-geopressure.R
For peer-review publication, it is essential that the data and code are accessible to reviewer. Because inaccurate labeling can lead to wrong trajectory, we highly encourage you to publish your data and code on Zenodo. This is made very easy using this github repository and this guide. This process will generate a DOI for your data and code which can be used in your repository. Here is an ey (e.g., https://zenodo.org/record/7471405)
What it needs to include:
- Generate a citation file with
usethis::use_citation()
andcffr
. - Use
renv
to make your work reproducible.