birdnet_run: Run BirdNET from RStudio (Warning: deprecated, see...

In nationalparkservice/NSNSDAcoustics: Streamline National Park Service Bioacoustics Analysis

Run BirdNET from RStudio (Warning: deprecated, see birdnet_analyzer instead.)

Description

This function uses the reticulate package to run Python from RStudio in order to process files through BirdNET. It is meant for Windows users and may have unexpected results on other systems. To use this function, users must first (1) install BirdNET-Lite (see here for a method to install on Windows) and (2) set up a conda environment for BirdNET. The function assumes that all files in a folder come from the same site, and that the audio files follow a SITEID_YYYYMMDD_HHMMSS.wav naming convention. Please input absolute paths for all directory arguments. This is necessary due to the way RStudio is communicating with the underlying Python code. Note that BirdNET's option to input a customized species list has not been implemented in this function.

Usage

birdnet_run(
  audio.directory,
  audio.files,
  results.directory,
  birdnet.directory,
  lat = -1,
  lon = -1,
  ovlp = 0,
  sens = 1,
  min.conf = 0.1
)

Arguments

audio.directory	Absolute path to audio files to be processed. Files are expected to have the naming convention SITEID_YYYYMMDD_HHMMSS.wav. Default behavior for this function is to process every file in the audio.directory through BirdNET.
audio.files	OPTIONAL character vector of specific file names to process within the audio.directory. If missing, all files in audio.directory will be processed.
results.directory	Absolute path to directory where BirdNET results should be stored.
birdnet.directory	Absolute path to directory where BirdNET is installed on your machine.
lat	Recording location latitude. Set -1 to ignore.
lon	Recording location longitude Set -1 to ignore.
ovlp	Overlap in seconds between extracted spectrograms. Values from 0.0 to 2.9. Default = 0.0.
sens	Detection sensitivity; higher values result in higher sensitivity. Values from 0.5 to 1.5. Default = 1.0.
min.conf	Minimum confidence threshold. Values from 0.01 to 0.99. Default = 0.1.

Details

This function is now deprecated.

This function was developed by the National Park Service Natural Sounds and Night Skies Division to act as a wrapper to process audio data using BirdNET. The example given in this function's documentation below will not run unless you have set up BirdNET-Lite and a conda environment as described in the Description.

The function can handle .wav or .mp3 audio files. The current behavior for .mp3 files is to convert to a temporary wave file for processing, and then delete the temporary file when finished. This behavior may not be necessary on all platforms and Python / conda installations.

Internally, BirdNET expects a week of the year as an input. The behavior of birdnet_run() is to parse the week of year from the SITEID_YYYYMMDD_HHMMSS filename using lubridate::week().

NSNSDAcoustics suggests the reticulate package but does not install it for you. To use this function, please install reticulate using install.packages('reticulate')

Value

Saves an unformatted CSV of results for each wave file in results.directory. Files have prefix "BirdNET_". If there is an issue with any audio files (e.g., wave file corrupt or too short), error messaging will be returned and problematic files that were not processed will be recorded in a file named 'BirdNET_Problem-Files_DATE.csv'. Note that problem files may also occur if you have CSV results open from previous runs and are attempting to re-run the results while the CSV is still open; the program will not have write permissions to overwrite an open CSV file.

Each CSV produced by BirdNET contains a single column with detections in semi-colon separated values of the following information:

• Start (s): Start time of detection in seconds.

• End (s): End time of detection in seconds.

• Scientific name: Species scientific name.

• Common name: Species common name.

• Confidence: BirdNET's confidence level in this detection ranging from 0 (least confident) to 1 (most confident).

The following list provides an example of these outputs:

• Start (s);End (s);Scientific name;Common name;Confidence

• 3.0;6.0;Catharus ustulatus;Swainson's Thrush;0.7575617

• 3.0;6.0;Setophaga occidentalis;Hermit Warbler;0.1371203

• 3.0;6.0;Setophaga townsendi;Townsend's Warbler;0.11865085

• 15.0;18.0;Catharus ustulatus;Swainson's Thrush;0.95675665

• 15.0;18.0;Setophaga occidentalis;Hermit Warbler;0.15624857

• 21.0;24.0;Catharus ustulatus;Swainson's Thrush;0.43174374

• 24.0;27.0;Catharus ustulatus;Swainson's Thrush;0.6530585

See Also

birdnet_format, birdnet_verify

Examples

## Not run: 

##### View examples of CSV outputs produced by birdnet_run(): #####
data(exampleBirdNET1)
write.csv(x = exampleBirdNET1,
          file = 'BirdNET_Rivendell_20210623_113602.csv',
          row.names = FALSE)

data(exampleBirdNET2)
write.csv(x = exampleBirdNET2,
          file = 'BirdNET_Rivendell_20210623_114602.csv',
          row.names = FALSE)



##### Please consider the following example as pseudocode ######

# Because this function uses two external programs (Python and BirdNET-Lite),
# the example function below will not be modifiable to run for you unless
# you follow the instructions given in "Description".

# Must set environment BEFORE calling in the reticulate package
Sys.setenv(RETICULATE_PYTHON = "C:/Your/Python/Path/Here/python.exe")
library(reticulate)

# Set your conda environment
use_condaenv(condaenv = "pybirdnet", required = TRUE)

# Create an audio directory for this example
dir.create('example-audio-directory')

# Create a results directory for this example
dir.create('example-results-directory')

# Read in example wave files
data(exampleAudio1)
data(exampleAudio2)

# Write example waves to example audio directory
tuneR::writeWave(object = exampleAudio1,
                 filename = 'example-audio-directory/Rivendell_20210623_113602.wav')
tuneR::writeWave(object = exampleAudio2,
                 filename = 'example-audio-directory/Rivendell_20210623_114602.wav')

# Run all audio data in a directory through BirdNET
birdnet_run(audio.directory = 'absolute/path/to/example-audio-directory',
            results.directory = 'absolute/path/to/example-results-directory',
            birdnet.directory = 'absolute/path/to/BirdNET',
            lat = 46.09924,
            lon = -123.8765)

# Use optional "audio.files" argument to process specific files
birdnet_run(audio.directory = 'absolute/path/to/example-audio-directory',
            audio.files = 'Rivendell_20210623_113602.wav',
            results.directory = 'absolute/path/to/example-results-directory',
            birdnet.directory = 'absolute/path/to/BirdNET',
            lat = 46.09924,
            lon = -123.8765)

# Delete all temporary example files when finished
unlink(x = 'example-audio-directory', recursive = TRUE)
unlink(x = 'example-results-directory', recursive = TRUE)


## End(Not run)

nationalparkservice/NSNSDAcoustics documentation built on March 4, 2025, 10:24 p.m.