calculate_vp {bioRad}R Documentation

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

calculate_vp(
  file,
  vpfile = "",
  pvolfile_out = "",
  autoconf = FALSE,
  verbose = FALSE,
  warnings = TRUE,
  mount,
  sd_vvp_threshold,
  rcs = 11,
  dual_pol = TRUE,
  rho_hv = 0.95,
  single_pol = TRUE,
  elev_min = 0,
  elev_max = 90,
  azim_min = 0,
  azim_max = 360,
  range_min = 5000,
  range_max = 35000,
  n_layer = 20,
  h_layer = 200,
  dealias = TRUE,
  nyquist_min = if (dealias) 5 else 25,
  dbz_quantity = "DBZH",
  mistnet = FALSE,
  mistnet_elevations = c(0.5, 1.5, 2.5, 3.5, 4.5),
  local_install,
  local_mistnet
)

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. Or a single pvol object. 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) a format supported by the RSL library or 3) Vaisala IRIS (IRIS RAW) format.

vpfile

Character. File name. When provided, writes a vertical profile file (vpfile) either in the VPTS CSV or 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.

autoconf

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

verbose

Logical. When TRUE, vol2bird stdout is piped to the R console.

warnings

Logical. When TRUE, vol2bird warnings are piped to the R console.

mount

Character. Directory path of the mount point for the Docker container (deprecated).

sd_vvp_threshold

Numeric. Lower threshold for the 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.

rcs

Numeric. Radar cross section per bird to use, in cm^2.

dual_pol

Logical. When TRUE, uses dual-pol mode, in which meteorological echoes are filtered using the correlation coefficient threshold rho_hv.

rho_hv

Numeric. Lower threshold in correlation coefficient to use for filtering meteorological scattering.

single_pol

Logical. When TRUE, uses precipitation filtering in single polarization mode based on reflectivity and radial velocity quantities.

elev_min

Numeric. Minimum elevation angle to include, in degrees.

elev_max

Numeric. Maximum elevation angle to include, in degrees.

azim_min

Numeric. Minimum azimuth to include, in degrees clockwise from north.

azim_max

Numeric. Maximum azimuth to include, in degrees clockwise from north.

range_min

Numeric. Minimum range to include, in m.

range_max

Numeric. Maximum range to include, in m.

n_layer

Numeric. Number of altitude layers to use in generated profile.

h_layer

Numeric. Width of altitude layers to use in generated profile, in m.

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 to include, in m/s.

dbz_quantity

Name of the available reflectivity factor to use if not DBZH (e.g. DBZV, TH, TV).

mistnet

Logical. Whether to use the MistNet segmentation model.

mistnet_elevations

Numeric vector of length 5. Elevation angles to feed to the MistNet segmentation model, which expects exactly 5 elevation scans at 0.5, 1.5, 2.5, 3.5 and 4.5 degrees. Specifying different elevation angles may compromise segmentation results.

local_install

Character. Path to local vol2bird installation (e.g. your/vol2bird_install_directory/vol2bird/bin/vol2bird.sh). (deprecated)

local_mistnet

Character. Path to local MistNet segmentation model in PyTorch format (e.g. ⁠/your/path/mistnet_nexrad.pt⁠).

Details

Typical use

Common arguments set by users are file, vpfile and autoconf. 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 and dual polarization mode when available. The default for S-band data is to apply precipitation filtering in dual-polarization mode only.

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.

sd_vvp_threshold

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.

rcs

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

dual_pol

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

azim_min / azim_max

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_min / range_max

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()). range_max may be extended up to 40 km (40000) for volumes with low elevations only, in order to extend coverage to higher altitudes.

h_layer

The algorithm has been tested and developed for altitude layers with h_layer = 200m. Smaller widths than 100 m 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.

dealias

Dealiasing uses the torus mapping method by Haase et al. (2004).

Local installation

You may point parameter local_mistnet to a local download of the MistNet segmentation model in PyTorch format, e.g. ⁠/your/path/mistnet_nexrad.pt⁠. The MistNet model can be downloaded at https://s3.amazonaws.com/mistnet/mistnet_nexrad.pt.

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 dealiasing data (dealias), please also cite Haase et al. (2004).

See Also

Examples

# Locate and read the polar volume example file
pvolfile_source <- system.file("extdata", "volume.h5", package = "bioRad")

# Copy the file to a temporary directory with read/write permissions
pvolfile <- paste0(tempdir(),"/volume.h5")
file.copy(pvolfile_source, pvolfile)

# Calculate the profile
if (requireNamespace("vol2birdR", quietly = TRUE)) {
vp <- calculate_vp(pvolfile)

# Get summary info
vp

# Clean up
file.remove(pvolfile)

}
[Package bioRad version 0.8.1 Index]