ohun is intended to facilitate the automated detection of sound events, providing functions to diagnose and optimize detection routines. It provides utilities for comparing detection and annotations of audio events described by frequency and time boxes.
The main features of the package are:
The package offers functions for:
The implementation of detection diagnostics that can be applied to both built-in detection methods and to those obtained from other software packages makes the package ohun a useful tool for conducting direct comparisons of the performance of different routines. In addition, the compatibility of ohun with data formats already used by other sound analysis R packages (e.g. seewave, warbleR) enables the integration of ohun into more complex acoustic analysis workflows in a popular programming environment within the research community.
All functions allow the parallelization of tasks (using the packages parallel and pbapply), which distributes the tasks among several processors to improve computational efficiency. The package works on sound files in ‘.wav’, ‘.mp3’, ‘.flac’ and ‘.wac’ format.
Install/load the package from CRAN as follows:
# From CRAN would be
install.packages("ohun")
#load package
library(ohun)To install the latest developmental version from github you will need the R package remotes:
remotes::install_github("ropensci/ohun")
#load package
library(ohun)Further system requirements due to the dependency seewave may be needed (e.g. ‘libsndfile’ and ‘fftw3’ on Linux). Take a look at this archived page for instructions on how to install/troubleshoot these external dependencies.
The package comes with example data so you can try out a detection
routine right away. The code below runs an energy-based detection on two
sound files and compares it against the reference annotations using diagnose_detection():
library(ohun)
# load example data
data("lbh1", "lbh2", "lbh_reference")
# save sound files into a temporary working directory
tuneR::writeWave(lbh1, file.path(tempdir(), "lbh1.wav"))
tuneR::writeWave(lbh2, file.path(tempdir(), "lbh2.wav"))
# detect sound events based on amplitude envelopes
detection <- energy_detector(
files = c("lbh1.wav", "lbh2.wav"),
path = tempdir(),
threshold = 6,
smooth = 6.8,
bp = c(2, 9),
hop.size = 3,
min.duration = 50
)
# compare the detection against the reference annotations
diagnose_detection(reference = lbh_reference, detection = detection)## detections true.positives false.positives false.negatives splits merges
## 1 19 19 0 0 0 0
## overlap recall precision f.score
## 1 0.8511668 1 1 1This returns a set of signal detection
theory indices (e.g. recall, precision, F score) that can be used to
evaluate and fine-tune the detection parameters. optimize_energy_detector()
automates this process by testing several parameter combinations at
once.
template_detector()
works in a similar way to energy_detector() (same
‘files’/‘path’ arguments and selection table output), but detects sound
events by cross-correlation with a template sound event instead of
amplitude thresholds, so its output can be evaluated with
diagnose_detection() and optimized with
optimize_template_detector() just like above.
Take a look at the vignettes for a more detailed overview of the main features of the package:
This package has been peer-reviewed by rOpenSci.
Please cite ohun as follows:
Araya-Salas, M., Smith-Vidaurre, G., Chaverri, G., Brenes, J. C., Chirino, F., Elizondo-Calvo, J., & Rico-Guevara, A. (2023). ohun: An R package for diagnosing and optimizing automatic sound event detection. Methods in Ecology and Evolution, 14, 2259–2271. https://doi.org/10.1111/2041-210X.14170