Apply MistNet segmentation to a polar volume

Apply MistNet segmentation model to a polar volume file on disk, and load the resultant segmentation as a polar volume (pvol) object.

apply_mistnet(
  file,
  pvolfile_out,
  verbose = FALSE,
  mount = dirname(file),
  load = TRUE,
  mistnet_elevations = c(0.5, 1.5, 2.5, 3.5, 4.5),
  local_install,
  local_mistnet
)

Arguments

file: character. File path for a radar polar volume.
pvolfile_out: character. (optional) Filename for the polar volume to be stored, including the MistNet segmentation results
verbose: Logical. When TRUE, Docker stdout is piped to the R console. Always TRUE on Windows.
mount: Character. Directory path of the mount point for the Docker container.
load: on completion load the data
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: (optional) String with path to local vol2bird binary (e.g. "/your/vol2bird_install_directory/vol2bird/bin/vol2bird.sh"), to use local installation instead of Docker container
local_mistnet: (optional) String with path to local mistnet segmentation model in PyTorch format (e.g. "/your/path/mistnet_nexrad.pt"), to use local installation instead of Docker container.

Value

If parameter load is TRUE an object of class pvol on success. If parameter load is FALSE, TRUE on success.

Details

MistNet is a deep convolutional neural network that has been trained using labels derived from S-band dual-polarization data across the US NEXRAD network.

It's purpose is to screen out areas of precipitation in weather radar data, primarily legacy data for which dual-polarization data are not available.

Because the network has been trained on S-band data, it may not perform as well on C-band.

MistNet requires three single-polarization parameters as input: reflectivity (DBZH), radial velocity (VRADH), and spectrum width (WRADH), at 5 specific elevation angles (0.5, 1.5, 2.5, 3.5 and 4.5 degrees). Based on these data it can estimate a segmentation mask that identifies pixels with weather that should be removed when interested only in biological data.

MistNet will calculate three class probabilities (from 0 to 1, with 1 corresponding to a 100% probability) as additional scan parameters to the polar volume:

"BACKGROUND": class probability that no signal was detected above the noise level of the radar
"WEATHER": class probability that weather was detected
"BIOLOGY": class probability that biological scatterers were detected

These class probabilities are only available for the 5 input elevations used as input for the MistNet model. Based on all the class probabilities a final weather segmentation map calculated, stored as scan parameter CELL, which is available for all elevation scans.

"CELL": Final weather segmentation, with values > 1 indicating pixels classified as weather, and values equal to 1 indicating pixels that are located within 5 km distance of a weather pixels

A pixel is classified as weather if the class probability WEATHER > 0.45 or when the average class probability for rain across all five MistNet elevation scans at that spatial location > 0.45.

MistNet may run more slowly on Windows than on Linux or Mac OSX.

See Lin et al. 2019 for details.

References

Please also cite this publication when using MistNet:

Lin T-Y, Winner K, Bernstein G, Mittal A, Dokter AM, Horten KG, Nilsson C, Van Doren B, Farnsworth A, La Sorte FA, Maji S, Sheldon D (2019) MistNet: Measuring historical bird migration in the US using archived weather radar data and convolutional neural networks. Methods in Ecology and Evolution 10: 1908– 1922. doi:10.1111/2041-210X.13280

Examples

# \dontrun{
# download a NEXRAD file, save as KBGM_example
download.file(paste("https://noaa-nexrad-level2.s3.amazonaws.com/",
  "2019/10/01/KBGM/KBGM20191001_000542_V06",
  sep = ""
), "~/KBGM_example")

# calculate MistNet segmentation:
mistnet_pvol <- apply_mistnet("~/KBGM_example")

# print summary info for the segmented elevation scan at 0.5 degree,
# verify new parameters BIOLOGY, WEATHER, BACKGROUND and CELL have been added:
my_scan <- get_scan(mistnet_pvol, 0.5)

# project the scan as a ppi:
my_ppi <- project_as_ppi(my_scan, range_max = 100000)
#> Warning: CRS object has comment, which is lost in output; in tests, see
#> https://cran.r-project.org/web/packages/sp/vignettes/CRS_warnings.html

# plot the reflectivity parameter:
plot(my_ppi, param = "DBZH")


# plot the MistNet class probability [0-1] for weather
plot(my_ppi, param = "WEATHER")


# plot the MistNet class probability [0-1] for biology
plot(my_ppi, param = "BIOLOGY")


# plot the final segmentation result, with values >1 indicating
# areas classified as weather, and value 1 pixels that fall within an
# additional 5 km fringe around weather areas.
plot(my_ppi, param = "CELL")


# clean up:
file.remove("~/KBGM_example")
#> [1] TRUE
# }