1 Get started

This chapter explains how to get you up and running. It assumes you are working in RStudio.

1.1 Install packages

First, you will need to install a number of R packages that we will use:

install.packages(c(
  "devtools",  # To install packages from GitHub
  "yaml",      # To read processing settings
  "dplyr",     # To process dataframes
  "loopr",     # To process dataframes with loops
  "lubridate", # To process dates
  "circular",  # To calculate circular means
  "bookdown"   # To generate this documentation
))
devtools::install_github("adokter/bioRad", ref="master") # To process vp data

1.2 Download code

To run or adapt the code in this document, fork or clone this repository: https://github.com/enram/vp-processing.

1.3 Define processing settings

The processing requires a number of settings we need to define. If you want to run the processing with other data and settings, then this is the only code you need to update (in setup.Rmd):

# Project name
project_name <- "example"

# Paths
# The paths below are creating by pasting the project_name into a full path string
# All paths are relative to this script (i.e. to the src directory).
# Make sure all directories exist!

# Where you store your raw data (needs a trailing slash)
raw_data_dir <- paste0("../data/raw/", project_name, "/")
# Where the processed vp data should go (needs a trailing slash)
processed_data_dir <- paste0("../data/processed/", project_name, "/")

# Your processing settings:
settings_file <- paste0("../settings/", project_name, "_processing_settings.yaml")
# The radar metadata (incl. coordinates):
radars_metadata_file <- "../settings/radar_metadata.csv"

1.4 Run processing

The processing of the vp data is done in several steps. Each has its own chapter and Rmd file:

  1. Get started (setup.Rmd) = this chapter
  2. Extract vp data and process for further analyses (extract_vp.Rmd)
  3. Process vp data for the Bird migration flow visualization (vp_to_flowviz.Rmd)

The repository comes with example settings and data for all steps, so you can run the processing out of the box:

  1. Go the src directory of the downloaded code
  2. Open vp-processing.Rproj in RStudio

1.4.1 Run all steps

To run all steps use the build functionality: it will run all the .Rmd files in src and generate fancy documentation:

  1. Click on the Build tab in RStudio
  2. Click the Build book button
  3. Wait for the build to finish

If you used the example data, nothing should have changed: you just reprocessed those files.

1.4.2 Run individual steps

If you are adapting the code, it can be useful to run individual steps. Except for setup.Rmd, all steps read input data file(s) and generate output data file(s). If those data files are already there, you don’t need to rerun the step that generated those. However, all files use the processing settings defined in setup.Rmd, so you need to run that file at least once first:

  1. Open and run setup.Rmd in RStudio
  2. Open and run one of the other .Rmd files
  3. Adapt the .Rmd file and run to test

1.5 Run your own processing

If you want to run the processing with your own data and processing settings, do this:

1.5.1 Upload your data

  1. Add a new directory to data/raw and give it a meaningful name
  2. Update raw_data_dir or rely on project_name in 1.3 so the code can find your directory
  3. Copy your vp data to that directory or download vp data from the ENRAM bird profile data repository

To download data, adapt the following code to your needs and run it. You might want to get some ☕ as this could take a while:

library(bioRad)
bioRad::download_vp(
  start_date = "2017-03-01",
  end_date = "2017-03-01",
  country = c("se"),
  radar = c("ang", "arl"),
  localpath = "../data/raw/my_data"
)

1.5.2 Update settings

  1. Copy and paste example_processing_settings.yaml in settings and give it a meaningful name
  2. Update settings_file in 1.3 so the code can find your file
  3. Adapt your settings file to your own needs

1.5.3 Update radars metadata

  1. Copy and paste radar_metadata.csv in settings and give it a meaningful name
  2. Update radars_metadata_file in 1.3 so the code can find your file
  3. Adapt your settings file to your own needs

Once done, run all steps of the processing. There should be no need to adapt the code.

1.6 Update code

If the processing doesn’t fit your needs, you can update the code by editing the relevant file in src and running it (see 1.4.2). If you encounter a bug in the original code, please let us know by filing an issue or submitting a pull request.

1.7 Update documentation

What your are reading here (in your browser) is in fact all generated from the .Rmd files in the src directory, using the R package bookdown.

If you notice a typo in this documentation, you can correct it by clicking the pencil icon in the menu at the top, which will take you straight to the correct .Rmd file in the original repository on GitHub. If you click the pencil icon on that GitHub page, you will be able to edit right away or create a copy (a fork) of the repository to do so, depending on your access rights.

If you want to generate your own fancy documentation 📕 from the adapted .Rmd files, then just run all steps. The build process will create your documentation in the docs repository. Open index.html in your browser to see it.

For more info on debugging or hosting your documentation (i.e. on GitHub pages), see this bookdown book on bookdown. 😊