calculate_vp {bioRad}R Documentation

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

Description

Calculates a vertical profile of biological scatterers (vp) from a polar volume (pvol) using the algorithm vol2bird (Dokter et al. 2011).

Usage

calculate_vp(
  file,
  vpfile = "",
  pvolfile_out = "",
  autoconf = FALSE,
  verbose = FALSE,
  mount = dirname(file[1]),
  sd_vvp_threshold,
  rcs = 11,
  dual_pol = FALSE,
  rho_hv = 0.95,
  elev_min = 0,
  elev_max = 90,
  azim_min = 0,
  azim_max = 360,
  range_min = 5000,
  range_max = 35000,
  n_layer = 20L,
  h_layer = 200,
  dealias = TRUE,
  nyquist_min = if (dealias) 5 else 25,
  dbz_quantity = "DBZH",
  mistnet = FALSE,
  local_install,
  pvolfile
)

Arguments

file

string or a vector of strings with radar file(s) for a radar polar volume. Provide either a single file containing a polar volume, or multiple files with single scans/sweeps. Data format should be either ODIM format, which is the implementation of the OPERA data information model in HDF5 format, or a format supported by the RSL library, or Vaisala IRIS (IRIS RAW) format.

vpfile

character. Filename for the vertical profile to be generated in ODIM HDF5 format (optional).

pvolfile_out

character. Filename for the polar volume to be generated in ODIM HDF5 format (optional, e.g. for converting RSL formats to ODIM).

autoconf

logical. When TRUE, default optimal configuration settings are selected automatically, and other user settings are ignored.

verbose

logical. When TRUE, pipe Docker stdout to R console. On Windows always TRUE.

mount

character. String with the mount point (a directory path) for the Docker container.

sd_vvp_threshold

numeric. Lower threshold in radial velocity standard deviation (profile quantity sd_vvp) in m/s. Biological signals with sd_vvp < sd_vvp_threshold are set to zero. Defaults to 2 m/s for C-band radars and 1 m/s for S-band radars if not specified.

rcs

numeric. Radar cross section per bird in cm^2.

dual_pol

logical. When TRUE use dual-pol mode, in which meteorological echoes are filtered using the correlation coefficient rho_hv. When FALSE use single polarization mode based only on reflectivity and radial velocity quantities.

rho_hv

numeric. Lower threshold in correlation coefficient used to filter meteorological scattering.

elev_min

numeric. Minimum scan elevation in degrees.

elev_max

numeric. Maximum scan elevation in degrees.

azim_min

numeric. Minimum azimuth in degrees clockwise from north.

azim_max

numeric. Maximum azimuth in degrees clockwise from north.

range_min

numeric. Minimum range in m.

range_max

numeric. Maximum range in m.

n_layer

numeric. Number of altitude layers in the profile.

h_layer

numeric. Width of altitude layers in meter.

dealias

logical. Whether to dealias radial velocities; this should typically be done when the scans in the polar volume have low Nyquist velocities (below 25 m/s).

nyquist_min

numeric. Minimum Nyquist velocity of scans in m/s for scans to be included in the analysis.

dbz_quantity

character. One of the available reflectivity factor quantities in the ODIM radar data format, e.g. DBZH, DBZV, TH, TV.

mistnet

logical. Whether to use MistNet segmentation model.

local_install

(optional) String with path to local vol2bird installation, see details.

pvolfile

deprecated argument renamed to file.

Details

Requires a running Docker daemon (unless a local installation of vol2bird is specified with local_install).

Common arguments set by users are file, vpfile, autoconf and mount.

Turn on autoconf to automatically select the optimal parameters for a given radar file. The default for C-band data is to apply rain-filtering in single polarization mode, as well as dual polarization mode when available.

The default for S-band data is to apply precipitation filtering in dual-polarization mode.

Arguments that sometimes require non-default values are: rcs, sd_vvp_threshold, range_max, dual_pol, dealias.

Other arguments are typically left at their defaults.

azim_min and azim_max only affects reflectivity-derived estimates in the profile (DBZH,eta,dens), not radial-velocity derived estimates (u, v, w, ff, dd, sd_vvp), which are estimated on all azimuths at all times. azim_min, azim_max may be set to exclude an angular sector with high ground clutter.

range_max may be extended up to 40,000 m for volumes with low elevations only, in order to extend coverage to higher altitudes.

For altitude layers with a VVP-retrieved radial velocity standard deviation value below the threshold sd_vvp_threshold, the bird density dens is set to zero (see vertical profile vp class). This threshold might be dependent on radar processing settings. Results from validation campaigns so far indicate that 2 m/s is the best choice for this parameter for most C-band weather radars, which is used as the C-band default. For S-band, the default threshold is 1 m/s. The algorithm has been tested and developed for altitude layers with h_layer = 200 m. Smaller widths are not recommended as they may cause instabilities of the volume velocity profiling (VVP) and dealiasing routines, and effectively lead to pseudo-replicated altitude data, since altitudinal patterns smaller than the beam width cannot be resolved.

The default radar cross section (11 cm^2) corresponds to the average value found by Dokter et al. in a calibration campaign of a full migration autumn season in western Europe at C-band. It's value may depend on radar wavelength. rcs will scale approximately M^{2/3} with M the bird's mass.

Using default values of range_min and range_max is recommended. Ranges closer than 5 km tend to be contaminated by ground clutter, while range gates beyond 35 km become too wide to resolve the default altitude layer width of 200 meter (see beam_width).

For dealiasing, the torus mapping method by Haase et al. is used.

At S-band (radar wavelength ~ 10 cm), currently only dual_pol=TRUE mode is recommended.

On repeated calls of calculate_vp, the Docker container mount can be recycled from one call to the next if subsequent calls share the same mount argument. Re-mounting a Docker container takes time, therefore it is advised to choose a mountpoint that is a parent directory of all volume files to be processed, such that calculate_vp calls are as fast as possible.

If you have installed the vol2bird algorithm locally (not possible on Windows) you can call vol2bird through this local installation (bypassing the Docker container), which will be faster. Simply point local_install to the path of your local vol2bird executable. Your local vol2bird executable will be called through a bash login shell. LD_LIBRARY_PATH (Linux) or DYLD_LIBRARY_PATH (Mac) should be correctly specified in your .bashrc or .bash_profile file and contain all the required shared libraries by vol2bird. See vol2bird installation pages on Github for details.

Value

A vertical profile object of class vp. When defined, output files vpfile and pvolfile_out are saved to disk.

References

Dokter et al. (2011) is the main reference for the profiling algorithm (vol2bird) underlying this function. When using the mistnet option, please also cite Lin et al. 2019. When de-aliasing data, please also cite Haase et al. 2004.

Examples

# locate example polar volume file:
pvolfile <- system.file("extdata", "volume.h5", package = "bioRad")

# copy to a home directory with read/write permissions:
file.copy(pvolfile, "~/volume.h5")

# calculate the profile:
## Not run: 
profile <- calculate_vp("~/volume.h5")
# print some summary info:
profile
# convert profile to a data.frame:
as.data.frame(profile)

## End(Not run)

# clean up:
file.remove("~/volume.h5")

[Package bioRad version 0.5.2 Index]