# Package overview

#### Marcelo Araya-Salas, PhD & Grace Smith-Vidaurre

#### 2025-10-21

The warbleR package is intended to facilitate the analysis of the structure of the animal acoustic signals in R. Users can enter their own data into a workflow that facilitates spectrographic visualization and measurement of acoustic parameters warbleR makes use of the fundamental sound analysis tools of the seewave package, and offers new tools for acoustic structure analysis. These tools are available for batch analysis of acoustic signals.

The main features of the package are:

- The use of loops to apply tasks through acoustic signals referenced in a selection table
- The production of image files with spectrograms that let users organize data and verify acoustic analyzes

The package offers functions for:

- Browse and download recordings of Xeno-Canto
- Explore, organize and manipulate multiple sound files
- Create spectrograms of complete recordings or individual signals
- Run different measures of acoustic signal structure
- Evaluate the performance of measurement methods
- Catalog signals
- Characterize different structural levels in acoustic signals
- Statistical analysis of duet coordination
- Consolidate databases and annotation tables

Most of the functions allow the parallelization of tasks, which distributes the tasks among several cores to improve computational efficiency. Tools to evaluate the performance of the analysis at each step are also available. All these tools are provided in a standardized workflow for the analysis of the signal structure, making them accessible to a wide range of users, including those without much knowledge of R. warbleR is a young package (officially published in 2017) currently in a maturation stage.

## Input acoustic data in warbleR

Most warbleR functions take as input annotation tables. An annotation table (or selection table in Raven’s and warbleR’s terminology) is a data set that contains information about the location in time (and sometimes in frequency) of the sounds of interest in one or more sound files. warbleR can take sound file annotations represented in the following R objects:

- Data frames
- Selection tables
- Extended selection tables

The data “lbh_selec_table” that comes with the package provides a good example will on the annotation data format used in warbleR:

    data("lbh_selec_table")

    lbh_selec_table

sound.files | channel | selec | start | end | bottom.freq | top.freq
--- | --- | --- | --- | --- | --- | ---
Phae.long1.wav | 1 | 1 | 1.1693549 | 1.3423884 | 2.220105 | 8.604378
Phae.long1.wav | 1 | 2 | 2.1584085 | 2.3214565 | 2.169437 | 8.807053
Phae.long1.wav | 1 | 3 | 0.3433366 | 0.5182553 | 2.218294 | 8.756604
Phae.long2.wav | 1 | 1 | 0.1595983 | 0.2921692 | 2.316862 | 8.822316
Phae.long2.wav | 1 | 2 | 1.4570585 | 1.5832087 | 2.284006 | 8.888027
Phae.long3.wav | 1 | 1 | 0.6265520 | 0.7577715 | 3.006834 | 8.822316
Phae.long3.wav | 1 | 2 | 1.9742132 | 2.1043921 | 2.776843 | 8.888027
Phae.long3.wav | 1 | 3 | 0.1233643 | 0.2545812 | 2.316862 | 9.315153
Phae.long4.wav | 1 | 1 | 1.5168116 | 1.6622365 | 2.513997 | 9.216586
Phae.long4.wav | 1 | 2 | 2.9326920 | 3.0768784 | 2.579708 | 10.235116
Phae.long4.wav | 1 | 3 | 0.1453977 | 0.2904966 | 2.579708 | 9.742279

Take a look at the vignette ‘Annotation data format’ for more details on annotation data formats.

## warbleR functions and the workflow of analysis in bioacoustics

Bioacoustic analyzes generally follow a specific processing sequence and analysis. This sequence can be represented schematically like this:

We can group warbleR functions according to the bioacoustic analysis stages.

### Get and prepare recordings

The `query_xc()` function allows you to search and download sounds from the free access database Xeno-Canto. You can also convert .mp3 files to .wav, change the sampling rate of the files and correct corrupt files, among other functions.

Function | Description | Works on | Output
--- | --- | --- | ---
check_sound_files | verify if sound files can be read | multiple wave files | data frame
consolidate | consolidate sound files in a single folder | multiple wave files | data frame and wave files
fix_wavs | fix waves that cannot be read in R | multiple wave files | wave files
mp32wav | convert multiple mp3 files to wav format | multiple mp3 files | wave files
query_xc | Search and download mp3 files from Xeno-Canto | Scientific names/data frame | mp3 files
resample_est | resample wave objects in ext. selection tables | extended selection tables | extended selection tables
remove_channels | remove channels in multiple wave files | multiple wave files | wave files
remove_silence | remove silences in multiple wave files | multiple wave files | wave files
duration_sound_files | measures duration in multiple wave files | multiple wave files | data frame
info_sound_files | extract recording parameters from multiple wave files | multiple wave files | data frame

### Annotating sound

It is recommended to make annotations in other programs and then import them into R (for example in Raven and import them with the Rraven package). However, warbleR offers some functions to facilitate manual or automatic annotation of sound files, as well as the subsequent manipulation:

Function | Description | Works on | Output
--- | --- | --- | ---
freq_range | detect frequency range in selection tables | multiple wave files | data frame
tailor_sels | interactive tailoring of selections | selection tables | selection tables

### Organize annotations

The annotations (or selection tables) can be manipulated and refined with a variety of functions. Selection tables can also be converted into the compact format extended selection tables:

Function | Description | Works on | Output
--- | --- | --- | ---
tailor_sels | interactive tailoring of selections | selection tables | selection tables
sort_colms | order columns in an intuitive way | selection tables | selection tables
cut_sels | save selections as individual wave files | selection tables | wave files
filter_sels | subset selection tables based on filtered image files | selection tables, ext. selection tables, images | selection tables, ext. selection tables
fix_extended_selection_table | add wave objects to extended selection tables | selection tables | extended selection tables
selection_table | create selection tables and extended selection tables | selection tables | selection tables, ext. selection tables
song_analysis | measures acoustic parameters at higher structural levels of organization | selection tables, ext. selection tables | data frame, selection tables

### Measure acoustic signal structure

Most warbleR functions are dedicated to quantifying the structure of acoustic signals listed in selection tables using batch processing. For this, 4 main measurement methods are offered:

1. Spectrographic parameters
2. Cross correlation
3. Dynamic time warping (DTW)
4. Statistical descriptors of cepstral coefficients

Most functions gravitate around these methods, or variations of these methods:

Function | Description | Works on | Output
--- | --- | --- | ---
freq_range | detect frequency range in selection tables | multiple wave files | data frame
song_analysis | measures acoustic parameters at higher structural levels of organization | selection tables, ext. selection tables | data frame, selection tables
compare_methods | compare the performance of methods to measure acoustic structure | selection tables, ext. selection tables | images
freq_DTW | measures dynamic time warping (DTW) on dominant/fundamental frequency contours | selection tables, ext. selection tables | (di)similarity matrix, images
freq_ts | mesaures dominant/fundamental frequency contours | selection tables, ext. selection tables | data frame with frequency contours
inflections | measures number of inflections in frequency contours | data frame with frequency contours | data frame
mfcc_stats | measures statistical descriptors of Mel cepstral coefficients | selection tables, ext. selection tables | data frame
multi_DTW | measures dynamic time warping (DTW) on multiple contours | selection tables, ext. selection tables | (di)similarity matrix
sig2noise | measures signal-to-noise ratio | selection tables, ext. selection tables | selection tables, ext. selection tables
spectro_analysis | measures spectrographic parameters | selection tables, ext. selection tables | data frame
cross_correlation | measurec spectrographic cross-correlation | selection tables, ext. selection tables | (di)similarity matrix

### Verify annotations

Functions are provided to detect inconsistencies in the selection tables or modify selection tables. The package also offers several functions to generate spectrograms showing the annotations, which can be organized by annotation categories. This allows you to verify if the annotations match the previously defined categories, which is particularly useful if the annotations were automatically generated.

Function | Description | Works on | Output
--- | --- | --- | ---
check_sels | double-check selection tables | selection tables | selection tables
overlapping_sels | finds (time) overlapping selections | selection tables, ext. selection tables | selection tables, ext. selection tables
catalog | creates spectrogram catalog | selection tables, ext. selection tables | images
catalog2pdf | convert catalogs to .pdf | images | images
spectrograms | create spectrogram images | selection tables, ext. selection tables | images
full_spectrograms | create spectrograms of whole sound files | multiple wave files, selection tables, ext. selection tables | images
full_spectrogram2pdf | convert full spectrograms to .pfg | images | images

### Visual inspection of annotations and measurements

Function | Description | Works on | Output
--- | --- | --- | ---
snr_spectrograms | plots spectrograms highlighting areas where signal-to-noise ratio is measured | selection tables, ext. selection tables | images
spectrograms | create spectrogram images | selection tables, ext. selection tables | images
track_freq_contour | create spectrogram images including frequency contours | selection tables, ext. selection tables | images
plot_coordination | create schematic plots of coordinated signals | data frame | images
full_spectrograms | create spectrograms of whole sound files | multiple wave files, selection tables, ext. selection tables | images

### Additional functions

Finally, warbleR offers functions to simplify the use of extended selection tables, organize large numbers of images with spectrograms and generate elaborated signal visualizations:

Function | Description | Works on | Output
--- | --- | --- | ---
is_extended_selection_table | check if object is extended selection tables | data frame | TRUE/FALSE
is_selection_table | check if object is selection tables | data frame | TRUE/FALSE
catalog2pdf | convert catalogs to .pdf | images | images
move_imgs | moves images among folders | images | images
map_xc | created maps from Xeno-Canto recordings | data frame | images
test_coordination | test statistical significance of vocal coordination | data frame | data frame
full_spectrogram2pdf | convert full spectrograms to .pfg | images | images
color_spectro | highlight signals with colors in a spectrogram | wave object | plot in R
freq_range_detec | detect frequency range in wave objetcs | wave object | data frame, plot in R
open_wd | open working directory |  |
phylo_spectro | plots phylogenetic trees with spectrograms | selection tables | plot in R
read_sound_file | read sound files and wave objects | selection tables, ext. selection tables | wave object
simulate_songs | simulate songs |  | wave object, wave file and selection table
tweak_spectro | creates mosaic plots with spectrograms with different display parameters | selection tables, ext. selection tables | images
warbleR_options | define global parameters for warbleR functions |  |

## References

1. Araya-Salas M, G Smith-Vidaurre & M Webster. 2017. Assessing the effect of sound file compression and background noise on measures of acoustic signal structure. Bioacoustics 4622, 1-17
2. Araya-Salas M, Smith-Vidaurre G (2017) warbleR: An R package to streamline analysis of animal acoustic signals. Methods Ecol Evol 8:184-191.

Session information

    R version 4.3.2 (2023-10-31)
    Platform: x86_64-pc-linux-gnu (64-bit)
    Running under: Ubuntu 22.04.2 LTS

    Matrix products: default
    BLAS:   /usr/lib/x86_64-linux-gnu/blas/libblas.so.3.10.0
    LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.10.0

    locale:
     [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C               LC_TIME=en_US.UTF-8
     [4] LC_COLLATE=en_US.UTF-8     LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8
     [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                  LC_ADDRESS=C
    [10] LC_TELEPHONE=C             LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C

    time zone: America/Costa_Rica
    tzcode source: system (glibc)

    attached base packages:
    [1] stats     graphics  grDevices utils     datasets  methods   base

    other attached packages:
    [1] kableExtra_1.4.0   warbleR_1.1.37     NatureSounds_1.0.5 knitr_1.50         seewave_2.2.3
    [6] tuneR_1.4.7

    loaded via a namespace (and not attached):
     [1] jsonlite_2.0.0     compiler_4.3.2     rjson_0.2.23       brio_1.1.5         Rcpp_1.1.0
     [6] xml2_1.4.0         stringr_1.5.2      bitops_1.0-9       parallel_4.3.2     signal_1.8-1
    [11] jquerylib_0.1.4    textshaping_1.0.4  systemfonts_1.3.1  scales_1.4.0       yaml_2.3.10
    [16] fastmap_1.2.0      R6_2.6.1           dtw_1.23-1         curl_7.0.0         MASS_7.3-55
    [21] svglite_2.2.1      bslib_0.9.0        RColorBrewer_1.1-3 rlang_1.1.6        testthat_3.2.3
    [26] stringi_1.8.7      cachem_1.1.0       xfun_0.53          sass_0.4.10        fftw_1.0-9
    [31] viridisLite_0.4.2  cli_3.6.5          magrittr_2.0.4     digest_0.6.37      rstudioapi_0.17.1
    [36] pbapply_1.7-4      lifecycle_1.0.4    vctrs_0.6.5        proxy_0.4-27       evaluate_1.0.5
    [41] glue_1.8.0         farver_2.1.2       RCurl_1.98-1.17    rmarkdown_2.30     httr_1.4.7
    [46] tools_4.3.2        htmltools_0.5.8.1