Biological Analysis and Visualization of Weather Radar Data

Extract, visualize and summarize aerial movements of birds and insects from weather radar data.


bioRad provides standardized methods for extracting and reporting biological signals from weather radars. It includes functionality to inspect low‐level radar data, process these data into meaningful biological information on animal speeds and directions at different altitudes in the atmosphere, visualize these biological extractions, and calculate further summary statistics.

To get started, see:

Installation

You can install the released version of bioRad from CRAN with:

install.packages("bioRad")

Alternatively, you can install the latest development version from GitHub with:

devtools::install_github("adokter/bioRad")

Then load the package with:

library(bioRad)
#> Welcome to bioRad version 0.4.0
#> Docker daemon running, Docker functionality enabled.

Attention!

Google has recently changed its API requirements, and ggmap - the package used by bioRad to overlay radar scans on maps - now requires users to provide an API key and enable billing in order to use Google imagery. bioRad switched to using stamen maps by default, which do not require special credentials.

ggmap itself is outdated on CRAN; its developers hope to have the new version up on CRAN soon, but until then, see ggmap Github page for how to install the latest development version.

Docker (optional)

You only need to install Docker to:

  • Process radar data into vertical profiles of biological targets with calculate_vp().
  • Read NEXRAD radar data with read_pvolfile(). Docker is not required for reading ODIM radar data.
  • Convert NEXRAD radar data to ODIM format with nexrad_to_odim().

Why? bioRad makes use of a C implementation of the vol2bird algorithm through Docker to do the above. All other bioRad functions will work without a Docker installation.

Installing Docker
  1. Go to Docker Desktop.
  2. Download Docker for Windows or Mac (free login required) and follow the installation instructions. Note that Docker for Windows requires Microsoft Windows 10 Professional or Enterprise 64-bit: installing Docker Toolbox for previous Windows versions will not work.
  3. Open the Docker application. The Docker (whale) icon will appear in your menu or task bar and indicate if it is running correctly.
  4. Make local drive(s) available for Docker containers:
    • On Windows: right click the Docker icon > Settings > Shared drives > Select the drive(s) where you will be processing radar files > Click Apply.
    • On Mac: click the Docker icon > Preferences > File sharing > Add the drive(s) where you will be processing radar files > Click Apply & Restart.
  5. In R do check_docker().
  6. You can now use the bioRad functionality that requires Docker.
Known issues with Docker
  1. Hyper-V / Virtualbox conflicts on Windows. Docker requires Hyper-V enabled, but Hyper-V can not run together with Virtualbox. To use Virtualbox you will need to disable Hyper-V, which also disables Docker, and requires a reboot of the system.
  2. For firewall issues on Windows, see this issue

Usage

Radar data example

bioRad can read weather radar data (= polar volumes) in the ODIM format and formats supported by the RSL library, such as NEXRAD data. NEXRAD data (US) are available as open data and on AWS.

Here we read an example polar volume data file with read_pvolfile(), extract the scan/sweep at elevation angle 3 with get_scan(), project the data to a plan position indicator with project_as_ppi() and plot the radial velocity of detected targets with plot():

library(tidyverse) # To pipe %>% the steps below
system.file("extdata", "volume.h5", package = "bioRad") %>%
  read_pvolfile() %>%
  get_scan(3) %>%
  project_as_ppi() %>%
  plot(param = "VRADH") # VRADH = radial velocity in m/s

Radial velocities towards the radar are negative, while radial velocities away from the radar are positive, so in this plot there is movement from the top right to the bottom left.

Vertical profile data example

Weather radar data can be processed into vertical profiles of biological targets using calculate_vp(). This type of data is available as open data for over 100 European weather radars.

Once vertical profile data are loaded into bioRad, these can be bound into time series using bind_into_vpts(). Here we read an example time series, project it on a regular time grid with regularize_vpts() and plot it with plot():

example_vpts %>%
  regularize_vpts() %>%
  plot()
#> projecting on 300 seconds interval grid...

The gray bars in the plot indicate gaps in the data.

The altitudes in the profile can be integrated with integrate_profile() resulting in a dataframe with rows for datetimes and columns for quantities. Here we plot the quantity migration traffic rate (column mtr) with plot():

my_vpi <- integrate_profile(example_vpts)
 
plot(my_vpi, quantity = "mtr") # mtr = migration traffic rate

To know the total number of birds passing over the radar during the full time series, we use the last value of the cumulative migration traffic (column mt):

my_vpi %>%
  pull(mt) %>% # Extract column mt as a vector
  last()
#> [1] 173023.8

For more exercises, see this tutorial.

Meta

  • We welcome contributions including bug reports.
  • License: MIT
  • Get citation information for bioRad in R doing citation("bioRad").
  • Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

News

bioRad 0.4.0

First release on CRAN! All issues included in this release can be found here.

  • get_param() added as new function to get parameters from scan (#132).

  • download_basemap() now uses Stamen basemaps by default (parameter source), so users do not need to request an API key for the previous default Google Maps (#163).

  • download_vpfiles() and select_vpfiles() now use 5 letter radar codes (parameter radars instead of radar and country), allow to skip already downloaded files (parameter overwrite = TRUE) and have improved download and error messages (#176).

  • read_pvolfile(), nexrad_to_odim() and calculate_vp() (all Docker dependent) can now read files from directories containing a space (#162).

  • Details for deprecated functions mt(), mtr(), cmt() are now displayed with function (#166).

  • README reviewed for easier installation and usage (#155).

  • Get started vignette is now based on figure and workflow from Dokter et al. (#168).

  • Introductory exercises vignette renamed to rad_aero_18.Rmd since it is based on the 2nd Radar Aeroecology Training School.

  • bioRad now has a code of conduct and contributing guidelines (#145).

bioRad 0.3.0

Release consistent with and in preparation of the bioRad methods paper (https://doi.org/10.1111/ecog.04028). All issues included in this release can be found here.

  • Functions (#84), arguments (#112) and objects (#80) have been renamed to be consistent (#51). Deprecated functions will remain functional for now, but we will trigger a warning: we advise to use the new functions names. See the lists for current functions and deprecated functions.

  • integrate_profile() replaces the functionality of cmt() (#75) and mt() (#76).

  • plot() can now be used for scans (#71), e.g. plot(example_scan).

  • Functions are organized in sections on the website (#110).

  • Changelog section (this page) has been added to website (#144).

  • Package R code is reorganized as one function = one file for easier maintenance (#50).

  • First tests are included for some functions.

  • Contributors (#90) and citation (#141) have been updated.

  • bioRad now has a hex logo (#137). ✨

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.

install.packages("bioRad")

0.4.0 by Adriaan M. Dokter, 4 months ago


https://github.com/adokter/bioRad, https://adokter.github.io/bioRad


Report a bug at https://github.com/adokter/bioRad/issues


Browse source code at https://github.com/cran/bioRad


Authors: Adriaan M. Dokter [aut, cre] , Peter Desmet [aut] , Stijn Van Hoey [aut] , Jurriaan Spaaks [ctb] , Lourens Veen [ctb] , Liesbeth Verlinden [ctb] , Hidde Leijnse [ctb]


Documentation:   PDF Manual  


MIT + file LICENSE license


Imports curl, fields, ggmap, ggplot2, graphics, methods, raster, rgdal, rhdf5, sp, stats, utils, maptools

Suggests knitr, testthat


See at CRAN