# Introduction to vol2birdR

#### Adriaan M. Dokter & Anders Henja

vol2birdR is an R package for calculating vertical profiles and other biological scatterers from weather radar data. The original vol2bird is written as a C-package and has been migrated to also work as an R package.

## Introduction

The vol2birdR package provides necessary functions to process polar volume data of C-band and S-band radars into vertical profiles of biological scatterers. This package also enables libtorch and the MistNet model for segmentation of meteorological and biological signals.

## Calculating vertical profiles

First, define a configuration instance, and modify configuration settings according to needs.

    # load the library
    library(vol2birdR)

    # create a configuration instance
    config<-vol2bird_config()

    # modify the configuration instance as needed
    # in this example we set the maximum range to 25 km:
    config$rangeMax <- 25000

The configuration object can be modified heavily. Learn more about the available options in the documentation of `vol2bird_config()`

Note that configuration objects are copied by reference by default, and true copies that can be used independently should be assigned using:

    config <- vol2bird_config()
    config_copy <- vol2bird_config(config)

Finally, the vertical profile can be calculated using function `vol2bird()`:

    vol2bird(file="/your/input/pvolfile",config=config, vpfile="/your/output/vpfile")

The input pvolfile needs to be in ODIM HDF5 format, IRIS RAW format, or NEXRAD format. The output vpfile containing the profile will be in ODIM HDF5 format.

## MistNet

### Installation

MistNet is a deep convolution neural net for segmenting out rain in S-band radar data, see the publication at https://besjournals.onlinelibrary.wiley.com/doi/full/10.1111/2041-210X.13280. To use MistNet, follow the following additional installation steps:

After installing and loading vol2birdR, run `install_mistnet()` from R. This will download libtorch from the download section of https://pytorch.org as well as a wrapper library from AWS that enables the mistnet functionality:

    # STEP 1: install mistnet libraries
    library(vol2birdR)
    install_mistnet()

After completing this step, the following command should evaluate to `TRUE`:

    mistnet_exists()

Next, the pytorch mistnet model needs to be downloaded, which is hosted at http://mistnet.s3.amazonaws.com/mistnet_nexrad.pt. Note that this file is large, over 500Mb. It can be downloaded directly from R using `install_mistnet_model()`:

    # STEP 2: download mistnet model:
    # install mistnet model into vol2birdR package:
    install_mistnet_model()

`install_mistnet_model()` installs the model by default into the vol2birdR package directory. As a result, when reinstalling vol2birdR the model file will have to be re-downloaded as well.

Alternatively, you can store the model in an alternative location outside the vol2birdR package directory. This has the advantage that you don’t have to re-download the model when reinstalling vol2birdR. Simply store the path of the mistnet_nexrad.pt file in the `mistNetPath` element of your configuration object (see `vol2bird_config()`)

vol2birdR will automatically locate the file if it is located at `/opt/vol2bird/etc/mistnet_nexrad.pt`, which can be done as follows:

    # create the directory
    # (in case of a permission-denied error, create the directory manually)
    dir.create("/opt/vol2bird/etc", recursive=TRUE)

    # download the model
    install_mistnet_model(path="/opt/vol2bird/etc/mistnet_nexrad.pt")

### Using MistNet

After installing the MistNet libraries and model file, a profile can be calculated as follows:

    # define configuration object:
    config <- vol2bird_config()

    # enable MistNet:
    config$useMistNet <- TRUE

    # calculate the profile:
    vol2bird(file="/your/input/pvolfile", config=config, vpfile="/your/output/vpfile")