Learn R Programming

bioRad

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:

More vignettes:

  • Range correction: estimate spatial images of vertically integrated density corrected for range effects.

Documentation for the latest development version can be found here.

Installation

Install system libraries

For OS X and Linux the GNU Scientific Library (GSL), PROJ and HDF5 libraries need to be installed as system libraries prior to installation, which are required by dependency package vol2birdR:

SystemCommand
OS X (using Homebrew)brew install hdf5 proj gsl
Debian-based systems (including Ubuntu)sudo apt-get install libhdf5-dev libproj-dev gsl-bin libgsl-dev
Systems supporting yum and RPMssudo yum install hdf5-devel proj-devel gsl gsl-devel

Additional required system libraries on Linux (Ubuntu)

The following system libraries are required before installing bioRad on Linux systems. In terminal, install these with:

sudo apt install libcurl4-openssl-dev
sudo apt install libssl-dev
sudo apt install libgdal-dev

Install bioRad

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:

# install.packages("devtools")
devtools::install_github("adokter/bioRad")

Then load the package with:

library(bioRad)
#> Welcome to bioRad version 0.10.0
#> using vol2birdR version 1.1.0 (MistNet installed)

(optional) Enable MistNet

To enable MistNet, the following vol2birdR commands should be executed:

vol2birdR::install_mistnet()
vol2birdR::install_mistnet_model()

Read the vol2birdR documentation for more details.

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()

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] 129491.5

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.

Copy Link

Version

Install

install.packages('bioRad')

Monthly Downloads

698

Version

0.10.0

License

MIT + file LICENSE

Issues

Pull Requests

Stars

Forks

Maintainer

Adriaan M. Dokter

Last Published

June 16th, 2025

Functions in bioRad (0.10.0)

bind_into_vpts

Bind vertical profiles (vp) into time series (vpts)
doy_noy

Look up day of year (doy) or night of year (noy)
dbz_to_eta

Convert reflectivity factor (dBZ) to reflectivity (eta)
convert_legacy

Convert legacy bioRad objects
eta_to_dbz

Convert reflectivity (eta) to reflectivity factor (dBZ)
download_pvolfiles

Download polar volume (pvol) files from the NEXRAD archive
download_vpfiles

Download vertical profile (vp) files from the ENRAM data repository
example_vpts

Time series of vertical profiles (vpts) example
extract_string

extract strings from a vector using regex, analog to stringr::str_extract
filter_vpts

Filter a time series of vertical profiles ('vpts').
filter_precip

Posthoc precipitation filter
is.pvolfile

Check if a file is a polar volume (pvol)
get_iris_raw_task

Check the task type of an IRIS RAW file
get_param

Get a parameter (param) from a scan (scan)
get_odim_object_type

Check the data type of an ODIM HDF5 file
composite_ppi

Create a composite of multiple plan position indicators (ppi)
clean_mixture

Partition mixtures of animals using assumptions on airspeeds.
integrate_to_ppi

Calculate a plan position indicator (ppi) of vertically integrated density adjusted for range effects
is.nan.data.frame

Identify NaN in a dataframe
get_quantity

Get a quantity from a vertical profile (vp) or time series of vertical profiles (vpts)
get_elevation_angles

Get elevation angles of a polar volume (pvol), scan (scan) or parameter (param)
check_night

Check if it is night at a given time and place
check_radar_codes

Check if radar codes are exactly 5 characters
gaussian_beam_profile

Gaussian beam profile as a function of height
project_as_ppi

Project a scan (scan) or parameter (param) to a plan position indicator (ppi)
list_vpts_aloft

List aloft urls for time series of vertical profiles (vpts) of radar stations
map

Map a plan position indicator (ppi) on a map
proj_to_wgs

A wrapper for sp::spTransform(). Converts projected coordinates to geographic (WGS84) coordinates.
nexrad_to_odim

Convert a NEXRAD polar volume file to an ODIM polar volume file
is.vpfile

Check if a file is a vertical profile (vp)
plot.vpi

Plot an integrated profile (vpi)
example_scan

Scan (scan) example
match_filenames

Match a set of regular expressions to a list of files
read_cajun

Read a vertical profile (vp) from UMASS Cajun text file
plot.vpts

Plot a time series of vertical profiles (vpts)
get_scan

Get a scan (scan) from a polar volume (pvol)
example_vp

Vertical profile (vp) example
skip_if_no_vol2birdR

Skip test if vol2birdR not installed
rcs

Get radar cross section
rcs<-

Set radar cross section
plot.scan

Plot a scan (scan) in polar coordinates
skip_if_no_mistnet

Skip test if no mistnet
skip_if_no_tidyselect

Skip test if no tidyselect
integrate_profile

Vertically integrate profiles (vp or vpts) into an integrated profile (vpi)
vplist_to_vpts

Bind vertical profiles (vp) into time series (vpts)
[.ppi

Subset a plan position indicator (ppi)
tidyverse

Tidyverse methods for bioRad objects
nyquist_velocity

Calculate Nyquist velocity for a given pulse repetition frequency (PRF)
plot.ppi

Plot a plan position indicator (ppi)
plot.vp

Plot a vertical profile (vp)
sd_vvp_threshold

Get threshold of the radial velocity standard deviation
select_vpfiles

Select vertical profile (vp) files from computer
summary.vpts

Inspect a time series of vertical profiles (vpts)
read_stdout

Read a time series of vertical profiles (vpts) from file
read_vp

Read a vertical profile (vp) from file
regularize_vpts

Regularize a time series of vertical profiles (vpts) on a regular time grid
scan_to_spatial

convert a polar scan into a spatial object.
scan_to_raster

convert a polar scan into a raster
sd_vvp_threshold<-

Set threshold of the radial velocity standard deviation
read_pvolfile

Read a polar volume (pvol) from file
read_vpfiles

Read a vertical profile (vp) or a list of vertical profiles (vp) from files
read_vpts

Read time series of vertical profiles (vpts) from file(s)
vpts_schema

ENRAM-defined VPTS schema
summary.vp

Inspect a vertical profile (vp)
summary.vpi

Inspect an integrated profile (vpi)
skip_if_no_aws.s3

Skip test if no aws.s3
skip_if_no_mapping

Skip test if missing dependencies for mapping
summary.pvol

Inspect a polar volume (pvol)
wgs_to_proj

A wrapper for sp::spTransform(). Converts geographic (WGS84) coordinates to a specified projection
sunrise_sunset

Calculate sunrise or sunset for a time and place
write_pvolfile

Write a polar volume (pvol) object to ODIM HDF5 file
summary.scan

Inspect a scan (scan)
summary.ppi

Inspect a plan position indicator (ppi)
summary.param

Inspect a parameter (param)
as.data.frame.vp

Convert a vertical profile (vp) or time series of vertical profiles (vpts) to a data frame
attribute_table

Extract a volume coverage pattern table with all attributes
apply_mistnet

Apply MistNet segmentation to a polar volume
beam_distance

Calculate radar beam distance
beam_height

Calculate radar beam height
as.vpts

Convert a dataframe into a vpts object
as.vp

Convert a dataframe into a vp object
beam_profile

Calculate vertical radiation profile
Math.scan

Mathematical and arithmetic operations on param's, scan's and pvol's
add_expected_eta_to_scan

Adds expected eta to a scan
calculate_vp

Calculate a vertical profile (vp) from a polar volume (pvol) file
beam_range

Calculate radar beam range
c.vp

Concatenate vertical profiles (vp) into a list of vertical profiles
beam_width

Calculate radar beam width
beam_profile_overlap

Calculate overlap between a vertical profile ('vp') and the vertical radiation profile emitted by the radar
bioRad-deprecated

Deprecated bioRad functions and data
check_date_format

Check if character date is in specific format
bioRad-package

bioRad: Biological Analysis and Visualization of Weather Radar Data
calculate_param

Calculate a new scan parameter