Type: Package
Title: Vertical Profiles of Biological Signals in Weather Radar Data
Version: 1.1.1
Date: 2025-06-25
Description: 'R' implementation of the 'vol2bird' software for generating vertical profiles of birds and other biological signals in weather radar data. See Dokter et al. (2011) <doi:10.1098/rsif.2010.0116> for a paper describing the methodology.
License: LGPL (≥ 3)
Language: en-US
URL: https://github.com/adokter/vol2birdR/, https://adriaandokter.com/vol2bird/
BugReports: https://github.com/adokter/vol2birdR/issues
Depends: R (≥ 4.0.0)
Imports: assertthat, methods, pkgbuild, Rcpp (≥ 1.0.4), rlang, utils, withr
LinkingTo: Rcpp, RcppGSL
RoxygenNote: 7.3.2
VignetteBuilder: knitr
SystemRequirements: GNU make, GSL, HDF5, PROJ
NeedsCompilation: yes
RcppModules: RaveIO, PolarVolume, Vol2Bird, Vol2BirdConfig
Suggests: knitr, rmarkdown, testthat (≥ 3.0.0)
Config/testthat/edition: 3
Copyright: file COPYRIGHTS
Encoding: UTF-8
Packaged: 2025-06-25 19:45:02 UTC; amd427
Author: Anders Henja [aut] (vol2birdR package author and author of RAVE and HLHDF libraries), Adriaan M. Dokter ORCID iD [aut, cre], Alexander Tedeschi ORCID iD [ctb], Tsung-Yu Lin [ctb] (contributor MistNet segmentation model), Subranshu Maji [ctb] (contributor MistNet segmentation model), Daniel Sheldon [ctb] (contributor MistNet segmentation model), Bart Kranstauber ORCID iD [ctb], Jurriaan H. Spaaks [ctb] (contributor to vol2bird library), Lourens Veen [ctb] (contributor to vol2bird library), Iwan Holleman [ctb] (contributor to vol2bird library), Hidde Leijnse [ctb] (contributor to vol2bird library), John H. Merritt [ctb, cph] (author of RSL library), Bart Kelley [ctb] (contributor and maintainer of RSL library), Mark Couture [ctb] (author of iris2odim add-on to RAVE library), Daniel Falbel [ctb] (contributor of original idea for building with torch support), Swedish Meteorological and Hydrological Institute, SMHI [cph] (copyright holder of HLHDF and RAVE libraries), GloBAM [fnd] (https://globam.science)
Maintainer: Adriaan M. Dokter <vol2birdr@cornell.edu>
Repository: CRAN
Date/Publication: 2025-06-25 20:10:02 UTC

vol2birdR: Vertical Profiles of Biological Signals in Weather Radar Data

Description

'R' implementation of the 'vol2bird' software for generating vertical profiles of birds and other biological signals in weather radar data. See Dokter et al. (2011) doi:10.1098/rsif.2010.0116 for a paper describing the methodology.

Details

To get started, see:

Author(s)

Maintainer: Adriaan M. Dokter vol2birdr@cornell.edu (ORCID)

Authors:

Other contributors:

See Also

Useful links:

PolarVolume

Description

The polar volume object as defined by RAVE.

The Rcpp PolarVolume class A polar volume

RaveIO routines

Description

Provides I/O routines using the rave framework

The Rcpp RaveIO class Used when loading and saving objects

Vol2Bird processor class

Description

The vol2bird processing class. Provides methods for processing polar volumes/scans.

The Rcpp vol2bird processing class.

See Also

vol2bird()

Vol2Bird configuration

Description

The vol2bird configuration used during processing

The Rcpp vol2bird configuration class. Configuration instance used when processing data.

See Also

vol2bird_config()

The default branch

Description

The default branch

Usage

branch

Format

An object of class character of length 1.

Initializes the mistnet shared library pointed to by the path

Description

Initializes the mistnet shared library pointed to by the path

Usage

cpp_mistnet_init(path)

Arguments

path

The shared library

The software has to be compiled with -DRAVE_MEMORY_DEBUG and without -DNO_RAVE_PRINTF. Manual handling for now.

Description

The software has to be compiled with -DRAVE_MEMORY_DEBUG and without -DNO_RAVE_PRINTF. Manual handling for now.

Usage

cpp_printMemory()

Returns the wsr88d site location file

Description

Returns the wsr88d site location file

Usage

cpp_vol2bird_get_wsr88d_site_location()

Value

location of site location file

Initializes the vol2birdR library

Description

Initializes the vol2birdR library

Usage

cpp_vol2bird_initialize()

Sets the main thread id

Description

Sets the main thread id

Usage

cpp_vol2bird_namespace__store_main_thread_id()

Sets the wsr88d site location file

Description

Sets the wsr88d site location file

Usage

cpp_vol2bird_set_wsr88d_site_location(loc)

Arguments

loc

location of file

Initializes the mistnet shared library pointed to by the path

Description

Initializes the mistnet shared library pointed to by the path

Usage

cpp_vol2bird_version()

List of installation files to download

Description

List the 'LibTorch' and 'MistNet' files to download as local files in order to proceed with install_mistnet_from_file().

Usage

get_install_urls(version = "1.10.2", type = install_type(version = version))

Arguments

version

The 'LibTorch' version to install.

type

The installation type for 'LibTorch'. Valid value is currently "cpu".

Value

a named list with character urls

See Also

Contains a list of 'MistNet' libraries for the various OS's

Description

Contains a list of 'MistNet' libraries for the various OS's

Usage

install_config

Format

An object of class list of length 2.

Install 'MistNet' libraries

Description

Installs libraries and dependencies for using 'MistNet'.

Usage

install_mistnet(
  version = "1.12.1",
  reinstall = FALSE,
  path = install_path(),
  timeout = 360,
  ...
)

Arguments

version

The 'LibTorch' version to install.

reinstall

Re-install 'MistNet' even if its already installed?

path

Optional path to install or check for an already existing installation.

timeout

Optional timeout in seconds for large file download.

...

other optional arguments (like `load` for manual installation).

Details

By default libraries are installed in the 'tools::R_user_dir("vol2birdR", "data")' directory.

When using path to install in a specific location, make sure the MISTNET_HOME environment variable is set to this same path to reuse this installation.

The TORCH_INSTALL environment variable can be set to 0 to prevent auto-installing 'LibTorch and TORCH_LOAD set to 0 to avoid loading dependencies automatically. These environment variables are meant for advanced use cases and troubleshooting only.

When timeout error occurs during library archive download, or length of downloaded files differ from reported length, an increase of the timeout value should help.

Value

no value returned. Installs libraries into the package

See Also

Examples


install_mistnet()

Install 'MistNet' libraries from files

Description

Installs 'LibTorch' and 'MistNet' dependencies from files.

Usage

install_mistnet_from_file(
  version = "1.12.1",
  libtorch,
  libmistnet,
  mistnet_model = NULL,
  ...
)

Arguments

version

The 'LibTorch' version to install.

libtorch

The installation archive file to use for 'LibTorch'. Shall be a "file://" URL scheme.

libmistnet

The installation archive file to use for 'MistNet'. Shall be a "file://" URL scheme.

mistnet_model

The installation archive file to use for the model. Shall be a "file://" URL scheme. Is optional!

...

other parameters to be passed to install_torch()

Details

When install_mistnet() initiated download is not possible, but installation archive files are present on local filesystem, install_mistnet_from_file() can be used as a workaround to installation issues. "libtorch" is the archive containing all 'LibTorch' modules, and "libmistnet" is the 'C' interface to 'LibTorch' that is used for the 'R' package. Both are highly platform dependent, and should be checked through get_install_urls() 

> get_install_urls()
$libtorch
[1] "https://download.pytorch.org/libtorch/cpu/libtorch-cxx11-abi-shared-with-deps-1.10.2%2Bcpu.zip"

$libmistnet
[1] "https://s3.amazonaws.com/vol2bird-builds/vol2birdr/refs/heads/main/latest/Linux-cpu.zip"

$mistnet_model
[1] "http://mistnet.s3.amazonaws.com/mistnet_nexrad.pt"

In a terminal, download above zip-files. 

%> mkdir /tmp/myfiles
%> cd /tmp/myfiles
%> wget https://download.pytorch.org/libtorch/cpu/libtorch-cxx11-abi-shared-with-deps-1.10.2%2Bcpu.zip
%> wget https://s3.amazonaws.com/vol2bird-builds/vol2birdr/refs/heads/main/latest/Linux-cpu.zip
%> wget http://mistnet.s3.amazonaws.com/mistnet_nexrad.pt

Then in R, type: 

> install_mistnet_from_file(libtorch="file:///tmp/myfiles/libtorch-cxx11-abi-shared-with-deps-1.10.2+cpu.zip",
     libmistnet="file:///tmp/myfiles/Linux-cpu.zip",
     mistnet_model="file:///tmp/myfiles/mistnet_nexrad.pt")

Value

a list with character urls

See Also

Examples

# get paths to files to be downloaded
get_install_urls()
# download the files to a directory on disk, e.g. to /tmp/myfile,
# then install with:
## Not run: 
install_mistnet_from_file(
     libtorch="file:///tmp/myfiles/libtorch-cxx11-abi-shared-with-deps-1.10.2+cpu.zip",
     libmistnet="file:///tmp/myfiles/Linux-cpu.zip",
     mistnet_model="file:///tmp/myfiles/mistnet_nexrad.pt")

## End(Not run)

Install 'MistNet' model file

Description

Installs the 'MistNet' model file in 'PyTorch' format

Usage

install_mistnet_model(
  reinstall = FALSE,
  path = file.path(torch_install_path(), "data", "mistnet_nexrad.pt"),
  timeout = 1800,
  from_url = "http://mistnet.s3.amazonaws.com/mistnet_nexrad.pt",
  method = "libcurl",
  ...
)

Arguments

reinstall

Re-install the model even if its already installed

path

Optional path to install or check for an already existing installation.

timeout

Optional timeout in seconds for large file download.

from_url

From where the 'MistNet' model file should be downloaded.

method

The download method to use, see download.file

...

other optional arguments (like `load` for manual installation).

Details

Download and install the 'MistNet' model file. By default the library is downloaded to data/mistnet_nexrad.pt in the 'tools::R_user_dir("vol2birdR", "data")' directory.

Alternatively, the model file can be downloaded to a different location, which has the advantage that it doesn't have to be redownloaded after a reinstall of 'vol2birdR'.

'vol2birdR' will automatically detect the model file if it is downloaded to ⁠/opt/vol2bird/etc/mistnet_nexrad.pt⁠, which can be done as follows 

install_mistnet_model(path="/opt/vol2bird/etc/mistnet_nexrad.pt")

Value

No value returned, this function downloads a file

Examples


install_mistnet_model()

Returns the system name

Description

Returns the system name

Usage

install_os()

Returns the path of the 'MistNet' libraries for specified version

Description

Returns the path of the 'MistNet' libraries for specified version

Usage

install_path(version = "1.0")

Arguments

version

The 'MistNet' version checked for

Value

the path to the libraries

Returns the LibTorch install type

Description

Returns the LibTorch install type

Usage

install_type(version)

Returns the path of the 'MistNet' libraries for specified version

Description

Returns the path of the 'MistNet' libraries for specified version

Usage

lib_installed(library_name, install_path)

Arguments

library_name

The name of the library searched for, either 'libmistnet' or 'LibTorch'

install_path

The location where to look for the libraries

Value

if anything could be located or not

Loads a volume vol2bird-style meaning that a number of different file formats are tried and eventually loaded.

Description

Loads a volume vol2bird-style meaning that a number of different file formats are tried and eventually loaded.

Usage

load_volume(file)

Arguments

file

name of file to be loaded

Value

The loaded volume as a Rcpp_PolarVolume that can be passed around

The default 'MistNet' version

Description

The default 'MistNet' version

Usage

mistnet_default()

Value

the default 'MistNet' version

Checks if the 'LibTorch' and 'MistNet' libraries have been installed or not.

Description

Checks if the 'LibTorch' and 'MistNet' libraries have been installed or not.

Usage

mistnet_exists()

Value

TRUE if both 'LibTorch' and 'MistNet' libraries can be found, otherwise FALSE

See Also

Installs the library

Description

Installs the library

Usage

mistnet_install_lib(
  library_name,
  library_url,
  install_path,
  source_path,
  filter,
  md5hash,
  inst_path
)

Arguments

library_name

The name of the library searched for, either 'libmistnet' or 'libtorch'

library_url

Where to fetch the library

install_path

Where to put the library

source_path

If library should be fetched from somewhere else

filter

Not used

md5hash

MD5 check

inst_path

inst path

Value

if anything could be located or not

Installs the 'MistNet' libraries

Description

Installs the 'MistNet' libraries

Usage

mistnet_install_libs(version, type, install_path, install_config)

Arguments

version

version to install

type

what type of libraries to be installed

install_path

Where libraries should be installed

install_config

the library config

Check if MistNet installation is complete

Description

Checks if the 'LibTorch' and 'MistNet' libraries have been installed, and that the mistnet model file has been downloaded.

Usage

mistnet_installed(path, verbose = FALSE)

Arguments

path

Optional non-default file path to check for the mistnet model file.

verbose

When TRUE print informative messages on missing library and model files.

Value

TRUE if the 'LibTorch' and 'MistNet' libraries can be found and the and the MistNet model file can be located, otherwise FALSE.

See Also

Initialize the 'MistNet' system if enabled.

Description

Initialize the 'MistNet' system if enabled.

Usage

mistnet_start(version = mistnet_default(), reload = FALSE, verbose = TRUE)

Arguments

version

version of 'MistNet' library

reload

if 'MistNet' library should be reloaded or not, default FALSE.

verbose

Logical, when TRUE prints text to console.

Retrieve or set the nexrad location file

Description

Retrieves and sets the path of the RSL nexrad location file

Usage

nexrad_station_file(file)

Arguments

file

A string containing the path of a location file. Do not specify to retrieve path of current location file.

Details

The RSL library stores the locations and names of NEXRAD stations in a fixed-width text file. This function retrieves the path of the location file, and allows one to set the path to a different location file.

Value

The path of the nexrad location file

Examples

# return current location file
nexrad_station_file()
# store nexrad station file path
file_path <- nexrad_station_file()
# set station location file
nexrad_station_file(file_path)

Convert a NEXRAD polar volume file to an ODIM polar volume file

Description

Convert a NEXRAD polar volume file to an ODIM polar volume file

Usage

rsl2odim(
  file,
  config,
  pvolfile_out = "",
  verbose = TRUE,
  update_config = FALSE
)

Arguments

file

Character (vector). Either a path to a single radar polar volume (pvol) file containing multiple scans/sweeps, or multiple paths to scan files containing a single scan/sweep. The file data format should be either 1) ODIM format, which is the implementation of the OPERA data information model in the HDF5 format, 2) NEXRAD format supported by the 'RSL' library or 3) Vaisala IRIS (IRIS RAW) format. IRIS format is not available on CRAN, see vol2birdR development version on Github.

config

optional configuration object of class Rcpp_Vol2BirdConfig, typically output from vol2bird_config

pvolfile_out

Character. File name. When provided, writes a polar volume (pvol) file in the ODIM HDF5 format to disk. Useful for converting 'RSL' formats to ODIM, and for adding 'MistNet' segmentation output.

verbose

logical. When TRUE print profile output to console.

update_config

logical. When TRUE processing options that are determined based on input file characteristics are returned and updated in the object specified by the config argument. Do not set to TRUE when vol2bird() is used in loops like lapply() or in parallel processes.

Value

No value returned, creates a file specified by pvolfile_out argument.

See Also

Examples


# define filenames
nexrad_file <- paste0(tempdir(),"/KBGM20221001_000243_V06")
odim_file <- paste0(tempdir(),"/KBGM20221001_000243_V06.h5")
# download NEXRAD file:
download.file("https://noaa-nexrad-level2.s3.amazonaws.com/2022/10/01/KBGM/KBGM20221001_000243_V06",
destfile = nexrad_file, mode="wb")
# convert NEXRAD file to ODIM hdf5 format:
rsl2odim(nexrad_file, pvolfile_out = odim_file)
# clean up
file.remove(nexrad_file)
file.remove(odim_file)

Skip test if tempdir() not accessible

Description

Some function tests require tempdir() to be writeable in package vol2birdR. This helper function allows to skip a test if tempdir() is not accessible Inspired by https://testthat.r-lib.org/articles/skipping.html#helpers.

Usage

skip_if_no_temp_access()

Returns the 'LibTorch' installation path.

Description

Returns the directory where the LibTorch library has been downloaded

Usage

torch_install_path()

Value

a character path

Examples

torch_install_path()

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

Description

Calculates a vertical profile of biological scatterers (vp) from a polar volume (pvol) file using the algorithm vol2bird (Dokter et al. 2011 doi:10.1098/rsif.2010.0116).

Usage

vol2bird(
  file,
  config,
  vpfile = "",
  pvolfile_out = "",
  verbose = TRUE,
  update_config = FALSE
)

Arguments

file

Character (vector). Either a path to a single radar polar volume (pvol) file containing multiple scans/sweeps, or multiple paths to scan files containing a single scan/sweep. The file data format should be either 1) ODIM format, which is the implementation of the OPERA data information model in the HDF5 format, 2) NEXRAD format supported by the 'RSL' library or 3) Vaisala IRIS (IRIS RAW) format. IRIS format is not available on CRAN, see vol2birdR development version on Github.

config

optional configuration object of class Rcpp_Vol2BirdConfig, typically output from vol2bird_config

vpfile

Character. File name. When provided with .csv extension, writes a vertical profile in VPTS CSV format. Provided with another or no extension, writes a vertical profile in the ODIM HDF5 format to disk.

pvolfile_out

Character. File name. When provided, writes a polar volume (pvol) file in the ODIM HDF5 format to disk. Useful for converting 'RSL' formats to ODIM, and for adding 'MistNet' segmentation output.

verbose

logical. When TRUE print profile output to console.

update_config

logical. When TRUE processing options that are determined based on input file characteristics are returned and updated in the object specified by the config argument. Do not set to TRUE when vol2bird() is used in loops like lapply() or in parallel processes.

Value

No value returned, creates a file specified by file argument

See Also

Examples

# Locate the polar volume example file
pvolfile <- system.file("extdata", "volume.h5", package = "vol2birdR")

# Create a configuration instance:
conf <- vol2bird_config()

# Define output file
output_file <- paste0(tempdir(), "/vp.h5")

# Calculate the profile:
vol2bird(file = pvolfile, config = conf, vpfile = output_file)

Create a 'vol2bird' configuration instance

Description

Creates or copies a 'vol2bird' configuration instance of class Rcpp_Vol2BirdConfig

Usage

vol2bird_config(config)

Arguments

config

a configuration instance to be copied.

Details

Copying configuration instances

All processing options for vol2bird() are set using a configuration instance of class Rcpp_Vol2BirdConfig In some cases it might be necessary to copy and modify configuration instance, for example when processing polar volume files with different settings. In these cases you can't copy the instance like: 

config<-vol2bird_config()
extra_config<-config

In the above example, the config and extra_config instances will both refer to the same object. (copy by reference). To avoid this (and make a copy by value), use: 

config<-vol2bird_config()
# create a copy identical to object config:
extra_config<-vol2bird_config(config)

User configuration options

The Rcpp_Vol2BirdConfig class object sets the following 'vol2bird' processing options:

Advanced configuration options

Changing these settings is rarely needed.

Algorithm constants

Changing any of these constants is not recommended

Debug printing options

Enable these printing options only for debugging purposes in a terminal, since large amounts of data will be dumped into the console.

Value

an object of class Rcpp_Vol2BirdConfig

See Also

Examples

# create a configuration instance
config <- vol2bird_config()
# list the the configuration elements:
config
# change the maximum range included in the profile generation to 40 km:
config$rangeMax <- 40000
# make a copy of the configuration instance:
config_copy <- vol2bird_config(config)

Return 'vol2bird' version

Description

Return version of the 'vol2bird' algorithm

Usage

vol2bird_version()

Value

an object of class numeric_version

Examples

# check installed 'vol2bird' version:
vol2bird_version()