vp) from a polar volume (pvol)Calculates a vertical profile of biological scatterers (vp) from a polar volume (pvol) using the algorithm vol2bird (Dokter et al. 2011).
calculate_vp(pvolfile, vpfile = "", pvolfile_out = "",
autoconf = FALSE, verbose = FALSE, mount = dirname(pvolfile),
sd_vvp_threshold = 2, 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 = 25000, n_layer = 20L,
h_layer = 200, dealias = TRUE, nyquist_min = if (dealias) 5 else
25, dbz_quantity = "DBZH")A radar file containing a radar polar volume, either in ODIM format, which is the implementation of the OPERA data information model in HDF5 format, or a format supported by the RSL library.
character. Filename for the vertical profile to be generated in ODIM HDF5 format (optional).
character. Filename for the polar volume to be generated in ODIM HDF5 format (optional, e.g. for converting RSL formats to ODIM).
logical. When TRUE, default optimal configuration settings are selected automatically, and other user settings are ignored.
logical. When TRUE, pipe Docker stdout to R console. On Windows always TRUE.
character. String with the mount point (a directory path) for the Docker container.
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.
numeric. Radar cross section per bird in cm^2.
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.
numeric. Lower threshold in correlation coefficient used to filter meteorological scattering.
numeric. Minimum scan elevation in degrees.
numeric. Maximum scan elevation in degrees.
numeric. Minimum azimuth in degrees clockwise from north.
numeric. Maximum azimuth in degrees clockwise from north.
numeric. Minimum range in km.
numeric. Maximum range in km.
numeric. Number of altitude layers in the profile.
numeric. Width of altitude layers in meter.
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).
numeric. Minimum Nyquist velocity of scans in m/s for scans to be included in the analysis.
character. One of the available reflectivity factor quantities in the ODIM radar data format, e.g. DBZH, DBZV, TH, TV.
A vertical profile object of class vp. When
defined, output files vpfile and pvolfile_out are saved to disk.
Requires a running Docker daemon.
Common arguments set by users are pvolfile, 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 weather radars.
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 25 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.
Haase, G. and Landelius, T., 2004. Dealiasing of Doppler radar velocities using a torus mapping. Journal of Atmospheric and Oceanic Technology, 21(10), pp.1566-1573.
Bird migration flight altitudes studied by a network of operational weather radars, Dokter et al., J. R. Soc. Interface 8 (54), pp. 30--43, 2011. https://doi.org/10.1098/rsif.2010.0116
# NOT RUN {
# 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")
# }
# NOT RUN {
# clean up:
file.remove("~/volume.h5")
# }
Run the code above in your browser using DataLab