Visual inspection and signal classification

Bioacoustics in R with `warbleR`

warbleR logo

Bioacoustics research encompasses a wide range of questions, study systems and methods, including the software used for analyses. The warbleR and Rraven packages leverage the flexibility of the R environment to offer a broad and accessible bioinformatics tool set. These packages fundamentally rely upon two types of data to begin bioacoustic analyses in R:

Sound files: Recordings in wav or mp3 format, either from your own research or open-access databases like xeno-canto
Selection tables: Selection tables contain the temporal coordinates (start and end points) of selected acoustic signals within recordings

Package repositories

These packages are both available on CRAN: warbleR, Rraven, as well as on GitHub: warbleR, Rraven. The GitHub repository will always contain the latest functions and updates. You can also check out an article in Methods in Ecology and Evolution documenting the warbleR package ^[1].

We welcome all users to provide feedback, contribute updates or new functions and report bugs to warbleR’s GitHub repository.

Please note that warbleR and Rraven use functions from the seewave, monitoR, tuneR and dtw packages internally. warbleR and Rraven have been designed to make bioacoustics analyses more accessible to R users, and such analyses would not be possible without the tools provided by the packages above. These packages should be given credit when using warbleR and Rraven by including citations in publications as appropriate (e.g. citation("seewave")).

Parallel processing in `warbleR`

Parallel processing, or using multiple cores on your machine, can greatly speed up analyses. All iterative warbleR functions now have parallel processing for Linux, Mac and Windows operating systems. These functions also contain progress bars to visualize progress during normal or parallel processing. See ^[1] for more details about improved running time using parallel processing.

Vignette introduction

Here we work on a case study of microgeographic vocal variation in long-billed hermit hummingbirds, Phaethornis longirostris ^[2] by:

Performing quality control processing on selected signals, including visual inspection and tailoring temporal coordinates
Making lexicons for visual classification of signals

This vignette can be run without an advanced understanding of R, as long as you know how to run code in your console. However, knowing more about basic R coding would be very helpful to modify the code for your research questions.

For more details about function arguments, input or output, read the documentation for the function in question (e.g. ?catalog).

Prepare for analyses

library(warbleR)

# set your working directory appropriately
# setwd("/path/to/working directory")

# run this if you have restarted RStudio between vignettes without saving your workspace (assuming that you are in your /home/username directory)
setwd(file.path(getwd(), "warbleR_example"))

# Check your location
getwd()

Obtain example acoustic data from xeno-canto

The open-access xeno-canto database is an excellent source of sound files across avian species. You can query this database by a species or genus of interest. The function query_xc has two types of output:

Metadata of recordings: geographic coordinates, recording quality, recordist, type of signal, etc.
Sound files: Sound files in mp3 format are returned if the argument download is set to TRUE.

We recommend downloading metadata first from xeno-canto, as this data can be filtered in R to more efficiently download recordings (e.g. only those relevant to your question).

Here, we will query the xeno-canto database to download more Phaethornis longirostris sound files for our question of how male songs vary at a microgeographic scale.

# Query xeno-canto for all Phaethornis recordings (e.g., by genus)
Phae <- query_xc(qword = "Phaethornis", download = FALSE)

# Check out the structure of resulting the data frame
str(Phae)

'data.frame':   899 obs. of  36 variables:
 $ Recording_ID     : int  406968 403856 403854 387711 275252 261696 261695 261694 261693 261692 ...
 $ Genus            : chr  "Phaethornis" "Phaethornis" "Phaethornis" "Phaethornis" ...
 $ Specific_epithet : chr  "yaruqui" "yaruqui" "yaruqui" "yaruqui" ...
 $ Subspecies       : chr  "" "" "" "" ...
 $ English_name     : chr  "White-whiskered Hermit" "White-whiskered Hermit" "White-whiskered Hermit" "White-whiskered Hermit" ...
 $ Recordist        : chr  "Myornis" "Myornis" "Myornis" "Jerome Fischer" ...
 $ Country          : chr  "Colombia" "Colombia" "Colombia" "Ecuador" ...
 $ Locality         : chr  "La Chocoana, Guachalito, Nuquí, Chocó" "La Chocoana, Guachalito, Nuquí, Chocó" "La Chocoana, Guachalito, Nuquí, Chocó" "Amagusa Reserve Pichincha" ...
 $ Latitude         : num  5.627 5.627 5.627 0.161 0.75 ...
 $ Longitude        : num  -77.4 -77.4 -77.4 -78.9 -78.9 ...
 $ Vocalization_type: chr  "flight call" "flight call" "flight call" "song" ...
 $ Audio_file       : chr  "//www.xeno-canto.org/406968/download" "//www.xeno-canto.org/403856/download" "//www.xeno-canto.org/403854/download" "//www.xeno-canto.org/387711/download" ...
 $ License          : chr  "//creativecommons.org/licenses/by-nc-sa/4.0/" "//creativecommons.org/licenses/by-nc-sa/4.0/" "//creativecommons.org/licenses/by-nc-sa/4.0/" "//creativecommons.org/licenses/by-nc-sa/4.0/" ...
 $ Url              : chr  "//www.xeno-canto.org/406968" "//www.xeno-canto.org/403856" "//www.xeno-canto.org/403854" "//www.xeno-canto.org/387711" ...
 $ Quality          : chr  "A" "A" "A" "A" ...
 $ Time             : chr  "?" "?" "?" "09:00" ...
 $ Date             : chr  "2018-08-00" "2017-08-00" "2017-08-00" "2017-09-24" ...
 $ Altitude         : chr  "30" "10" "10" "1300" ...
 $ Spectrogram_small: chr  "//www.xeno-canto.org/sounds/uploaded/OXSIOLJJUP/ffts/XC406968-small.png" "//www.xeno-canto.org/sounds/uploaded/OXSIOLJJUP/ffts/XC403856-small.png" "//www.xeno-canto.org/sounds/uploaded/OXSIOLJJUP/ffts/XC403854-small.png" "//www.xeno-canto.org/sounds/uploaded/JPBSNBUUEF/ffts/XC387711-small.png" ...
 $ Spectrogram_med  : chr  "//www.xeno-canto.org/sounds/uploaded/OXSIOLJJUP/ffts/XC406968-med.png" "//www.xeno-canto.org/sounds/uploaded/OXSIOLJJUP/ffts/XC403856-med.png" "//www.xeno-canto.org/sounds/uploaded/OXSIOLJJUP/ffts/XC403854-med.png" "//www.xeno-canto.org/sounds/uploaded/JPBSNBUUEF/ffts/XC387711-med.png" ...
 $ Spectrogram_large: chr  "//www.xeno-canto.org/sounds/uploaded/OXSIOLJJUP/ffts/XC406968-large.png" "//www.xeno-canto.org/sounds/uploaded/OXSIOLJJUP/ffts/XC403856-large.png" "//www.xeno-canto.org/sounds/uploaded/OXSIOLJJUP/ffts/XC403854-large.png" "//www.xeno-canto.org/sounds/uploaded/JPBSNBUUEF/ffts/XC387711-large.png" ...
 $ Spectrogram_full : chr  "//www.xeno-canto.org/sounds/uploaded/OXSIOLJJUP/ffts/XC406968-full.png" "//www.xeno-canto.org/sounds/uploaded/OXSIOLJJUP/ffts/XC403856-full.png" "//www.xeno-canto.org/sounds/uploaded/OXSIOLJJUP/ffts/XC403854-full.png" "//www.xeno-canto.org/sounds/uploaded/JPBSNBUUEF/ffts/XC387711-full.png" ...
 $ Length           : chr  "0:02" "0:04" "0:01" "0:50" ...
 $ Uploaded         : chr  "2018-03-23" "2018-02-28" "2018-02-28" "2017-09-27" ...
 $ Other_species    : chr  "" "Coereba flaveola" "" "" ...
 $ Remarks          : chr  "In forest." "Forest border." "Forest border." "" ...
 $ Bird_seen        : chr  "yes" "yes" "yes" "yes" ...
 $ Playback_used    : chr  "no" "no" "no" "no" ...
 $ Other_species1   : chr  NA NA NA NA ...
 $ Other_species2   : chr  NA NA NA NA ...
 $ Other_species3   : chr  NA NA NA NA ...
 $ Other_species4   : chr  NA NA NA NA ...
 $ Other_species5   : chr  NA NA NA NA ...
 $ Other_species6   : chr  NA NA NA NA ...
 $ Other_species7   : chr  NA NA NA NA ...
 $ Other_species8   : chr  NA NA NA NA ...

# Query xeno-canto for all Phaethornis longirostris recordings
Phae.lon <- query_xc(qword = "Phaethornis longirostris", download = FALSE)

# Check out the structure of resulting the data frame
str(Phae.lon)

'data.frame':   85 obs. of  31 variables:
 $ Recording_ID     : int  497036 495384 433645 402755 355350 282529 274377 271499 154138 154129 ...
 $ Genus            : chr  "Phaethornis" "Phaethornis" "Phaethornis" "Phaethornis" ...
 $ Specific_epithet : chr  "longirostris" "longirostris" "longirostris" "longirostris" ...
 $ Subspecies       : chr  "" "cephalus" "" "" ...
 $ English_name     : chr  "Long-billed Hermit" "Long-billed Hermit" "Long-billed Hermit" "Long-billed Hermit" ...
 $ Recordist        : chr  "Jerome Fischer" "Guy Kirwan" "Oscar Campbell" "Marilyn Castillo" ...
 $ Country          : chr  "Panama" "Panama" "Panama" "Mexico" ...
 $ Locality         : chr  "Achiote Road, Colón Province" "Panama Rainforest Discovery Centre" "Panama Rainforest Discovery Centre" "Boca de Chajul, Marqués de Comillas, Chiapas" ...
 $ Latitude         : num  9.2 9.13 9.13 16.13 8.94 ...
 $ Longitude        : num  -80 -79.7 -79.7 -90.9 -78.5 ...
 $ Vocalization_type: chr  "song" "call" "song" "alarm call" ...
 $ Audio_file       : chr  "//www.xeno-canto.org/497036/download" "//www.xeno-canto.org/495384/download" "//www.xeno-canto.org/433645/download" "//www.xeno-canto.org/402755/download" ...
 $ License          : chr  "//creativecommons.org/licenses/by-nc-sa/4.0/" "//creativecommons.org/licenses/by-nc-sa/4.0/" "//creativecommons.org/licenses/by-nc-sa/4.0/" "//creativecommons.org/licenses/by-nc-nd/4.0/" ...
 $ Url              : chr  "//www.xeno-canto.org/497036" "//www.xeno-canto.org/495384" "//www.xeno-canto.org/433645" "//www.xeno-canto.org/402755" ...
 $ Quality          : chr  "no score" "A" "A" "A" ...
 $ Time             : chr  "09:30" "09:00" "08:30" "07:30" ...
 $ Date             : chr  "2019-02-10" "2019-07-04" "2018-07-10" "2016-01-18" ...
 $ Altitude         : chr  "30" "70" "70" "180" ...
 $ Spectrogram_small: chr  "//www.xeno-canto.org/sounds/uploaded/JPBSNBUUEF/ffts/XC497036-small.png" "//www.xeno-canto.org/sounds/uploaded/BZVYBRUAAE/ffts/XC495384-small.png" "//www.xeno-canto.org/sounds/uploaded/RFRTVEHIZX/ffts/XC433645-small.png" "//www.xeno-canto.org/sounds/uploaded/CHRIDPJVMH/ffts/XC402755-small.png" ...
 $ Spectrogram_med  : chr  "//www.xeno-canto.org/sounds/uploaded/JPBSNBUUEF/ffts/XC497036-med.png" "//www.xeno-canto.org/sounds/uploaded/BZVYBRUAAE/ffts/XC495384-med.png" "//www.xeno-canto.org/sounds/uploaded/RFRTVEHIZX/ffts/XC433645-med.png" "//www.xeno-canto.org/sounds/uploaded/CHRIDPJVMH/ffts/XC402755-med.png" ...
 $ Spectrogram_large: chr  "//www.xeno-canto.org/sounds/uploaded/JPBSNBUUEF/ffts/XC497036-large.png" "//www.xeno-canto.org/sounds/uploaded/BZVYBRUAAE/ffts/XC495384-large.png" "//www.xeno-canto.org/sounds/uploaded/RFRTVEHIZX/ffts/XC433645-large.png" "//www.xeno-canto.org/sounds/uploaded/CHRIDPJVMH/ffts/XC402755-large.png" ...
 $ Spectrogram_full : chr  "//www.xeno-canto.org/sounds/uploaded/JPBSNBUUEF/ffts/XC497036-full.png" "//www.xeno-canto.org/sounds/uploaded/BZVYBRUAAE/ffts/XC495384-full.png" "//www.xeno-canto.org/sounds/uploaded/RFRTVEHIZX/ffts/XC433645-full.png" "//www.xeno-canto.org/sounds/uploaded/CHRIDPJVMH/ffts/XC402755-full.png" ...
 $ Length           : chr  "0:27" "0:49" "0:58" "0:03" ...
 $ Uploaded         : chr  "2019-09-13" "2019-09-01" "2018-09-09" "2018-02-14" ...
 $ Other_species    : chr  "" "" "" "" ...
 $ Remarks          : chr  "" "Lek with up to three different individuals. Focal bird was perched 1.5 m above ground on a 45-degree angle twig." "Male seen on lek; 3 feet above ground in gap in undergrowth. Calling incessantly and quivering tail as doing so"| __truncated__ "" ...
 $ Bird_seen        : chr  "yes" "yes" "yes" "yes" ...
 $ Playback_used    : chr  "no" "no" "no" "no" ...
 $ Other_species1   : chr  NA NA NA NA ...
 $ Other_species2   : chr  NA NA NA NA ...
 $ Other_species3   : chr  NA NA NA NA ...

You can then use the function map_xc to visualize the geographic spread of the queried recordings. map_xc will create an image file of a map per species in your current directory if img = TRUE. If img = FALSE, maps will be displayed in the graphics device.

# Image type default is jpeg, but tiff files have better resolution

# When the data frame contains multiple species, this will yield one map per species
map_xc(X = Phae, img = TRUE, it = "tiff") # all species in the genus
map_xc(X = Phae.lon, img = FALSE) # a single species

Filter xeno-canto recordings by quality, signal type and locality

In most cases, you will need to filter the xeno-canto metadata by type of signal you want to analyze. When you subset the metadata, you can input the filtered metadata back into query_xc to download only the selected recordings. There are many ways to filter data in R, and the example below can be modified to fit your own data.

Here, before downloading the sound files themselves from xeno-canto, we want to ensure that we select high quality sound files that contain songs (rather than other acoustic signal types) and were also recorded at La Selva Biological Station in Costa Rica.

# How many recordings are available for Phaethornis longirostris?
nrow(Phae.lon)

[1] 85

# How many signal types exist in the xeno-canto metadata?
unique(Phae.lon$Vocalization_type)

 [1] "song"              "call"              "alarm call"        "song at lek"       "lekking"           "flight call"       "calls"            
 [8] "300"               "song, wing whirrs" "lek, song"

# How many recordings per signal type?
table(Phae.lon$Vocalization_type)


              300        alarm call              call             calls       flight call         lek, song           lekking              song 
                1                 1                 6                 1                 2                 2                 1                68 
      song at lek song, wing whirrs 
                2                 1

# Filter the metadata to select the signals we want to retain

# First by quality
Phae.lon <- Phae.lon[Phae.lon$Quality == "A", ]
nrow(Phae.lon)

[1] 12

# Then by signal type
Phae.lon.song <- Phae.lon[grep("song", Phae.lon$Vocalization_type, ignore.case = TRUE), ]
nrow(Phae.lon.song)

[1] 9

# Finally by locality
Phae.lon.LS <- Phae.lon.song[grep("La Selva Biological Station, Sarapiqui, Heredia", Phae.lon.song$Locality, ignore.case = FALSE), ]

# Check resulting data frame, 6 recordings remain
str(Phae.lon.LS)

'data.frame':   3 obs. of  31 variables:
 $ Recording_ID     : int  154138 154129 154072
 $ Genus            : chr  "Phaethornis" "Phaethornis" "Phaethornis"
 $ Specific_epithet : chr  "longirostris" "longirostris" "longirostris"
 $ Subspecies       : chr  "" "" ""
 $ English_name     : chr  "Long-billed Hermit" "Long-billed Hermit" "Long-billed Hermit"
 $ Recordist        : chr  "Marcelo Araya-Salas" "Marcelo Araya-Salas" "Marcelo Araya-Salas"
 $ Country          : chr  "Costa Rica" "Costa Rica" "Costa Rica"
 $ Locality         : chr  "La Selva Biological Station, Sarapiqui, Heredia" "La Selva Biological Station, Sarapiqui, Heredia" "La Selva Biological Station, Sarapiqui, Heredia"
 $ Latitude         : num  10.4 10.4 10.4
 $ Longitude        : num  -84 -84 -84
 $ Vocalization_type: chr  "song" "song" "song"
 $ Audio_file       : chr  "//www.xeno-canto.org/154138/download" "//www.xeno-canto.org/154129/download" "//www.xeno-canto.org/154072/download"
 $ License          : chr  "//creativecommons.org/licenses/by-nc-sa/3.0/" "//creativecommons.org/licenses/by-nc-sa/3.0/" "//creativecommons.org/licenses/by-nc-sa/3.0/"
 $ Url              : chr  "//www.xeno-canto.org/154138" "//www.xeno-canto.org/154129" "//www.xeno-canto.org/154072"
 $ Quality          : chr  "A" "A" "A"
 $ Time             : chr  "14:18" "10:09" "7:05"
 $ Date             : chr  "2010-05-21" "2010-05-21" "2010-05-28"
 $ Altitude         : chr  "" "" ""
 $ Spectrogram_small: chr  "//www.xeno-canto.org/sounds/uploaded/EMCWQLLKEW/ffts/XC154138-small.png" "//www.xeno-canto.org/sounds/uploaded/EMCWQLLKEW/ffts/XC154129-small.png" "//www.xeno-canto.org/sounds/uploaded/EMCWQLLKEW/ffts/XC154072-small.png"
 $ Spectrogram_med  : chr  "//www.xeno-canto.org/sounds/uploaded/EMCWQLLKEW/ffts/XC154138-med.png" "//www.xeno-canto.org/sounds/uploaded/EMCWQLLKEW/ffts/XC154129-med.png" "//www.xeno-canto.org/sounds/uploaded/EMCWQLLKEW/ffts/XC154072-med.png"
 $ Spectrogram_large: chr  "//www.xeno-canto.org/sounds/uploaded/EMCWQLLKEW/ffts/XC154138-large.png" "//www.xeno-canto.org/sounds/uploaded/EMCWQLLKEW/ffts/XC154129-large.png" "//www.xeno-canto.org/sounds/uploaded/EMCWQLLKEW/ffts/XC154072-large.png"
 $ Spectrogram_full : chr  "//www.xeno-canto.org/sounds/uploaded/EMCWQLLKEW/ffts/XC154138-full.png" "//www.xeno-canto.org/sounds/uploaded/EMCWQLLKEW/ffts/XC154129-full.png" "//www.xeno-canto.org/sounds/uploaded/EMCWQLLKEW/ffts/XC154072-full.png"
 $ Length           : chr  "2:58" "2:25" "3:09"
 $ Uploaded         : chr  "2013-11-11" "2013-11-11" "2013-11-11"
 $ Other_species    : chr  "" "" ""
 $ Remarks          : chr  "Recording equipment: Marantz Pmd 660+sennheiser ME67. Comments: individuo-AK; lek-Sura. Primera parte de grabac"| __truncated__ "Recording equipment: Marantz Pmd 660+sennheiser ME67. Comments: individuo-AK; lek-Sura. video 511, revisar. 9 m"| __truncated__ "Recording equipment: Marantz Pmd 660+sennheiser ME67. Comments: individuo-VA; lek-CCL. en percha ded VA, probab"| __truncated__
 $ Bird_seen        : chr  "yes" "yes" "yes"
 $ Playback_used    : chr  "no" "no" "no"
 $ Other_species1   : chr  NA NA NA
 $ Other_species2   : chr  NA NA NA
 $ Other_species3   : chr  NA NA NA

We can check if the location coordinates make sense (all recordings should be from a single place in Costa Rica) by making a map of these recordings using map_xc.

# map in the RStudio graphics device (img = FALSE)
map_xc(Phae.lon.LS, img = FALSE)

Once you’re sure you want the recordings, use query_xc to download the files. Also, save the metadata as a .csv file.

# Download sound files
query_xc(X = Phae.lon.LS)

# Save the metadata object as a .csv file
write.csv(Phae.lon.LS, "Phae_lon.LS.csv", row.names = FALSE)

Convert xeno-canto mp3 recordings to wav format

xeno-canto maintains recordings in mp3 format due to file size restrictions. However, we require wav format for all downstream analyses. Compression from wav to mp3 and back involves information losses, but recordings that have undergone this transformation have been successfully used in research ^[3].

To convert mp3 to wav, we can use the warbleR function mp32wav, which relies on a underlying function from the tuneR package. This function does not always work (and it remains unclear as to why!). This bug should be fixed in future versions of tuneR. If RStudio aborts when running mp32wav, use an mp3 to wav converter online, or download the open source software Audacity (available for Mac, Linux and Windows users).

After mp3 files have been converted, we need to check that the wav files are not corrupted and can be read into RStudio (some wav files can’t be read due to format or permission issues).

# Always check you're in the right directory beforehand
# getwd()

# here we are downsampling the original sampling rate of 44.1 kHz to speed up downstream analyses in the vignette series
mp32wav(samp.rate = 22.05)

# Use checkwavs to see if wav files can be read
check_sound_files()

Find overlapping selections

Overlapping selections can sometimes arise after selecting signals using other functions or software. The function below helps you detect overlapping signals in your selection table, and has arguments that you can play around with for overlap detection, renaming or deleting overlapping selections.

# To run this example:
# Open Phae_hisnr.csv and modify the start coordinate of the first selection and the end coordinate of the second selection so that the signals overlap

Phae.hisnr <- read.csv("Phae_hisnr.csv", header = TRUE)
str(Phae.hisnr)
head(Phae.hisnr, n = 15)

# yields a data frame with an additional column (ovlp.sels) that indicates which selections overlap
Phae.hisnr <- overlapping_sels(X = Phae.hisnr, max.ovlp = 0)

# run the function again but this time retain only the signals that don't overlap
Phae.hisnr <- overlapping_sels(X = Phae.hisnr, max.ovlp = 0, drop = TRUE)

Make spectrograms of selections

spectrograms generates spectrograms of individual selected signals. These image files can be used to filter out selections that were poorly made or represent signals that are not relevant to your analysis. This quality control step is important for visualizing your selected signals after any selection method, even if you imported your selections from Raven or Syrinx.

spectrograms(Phae.hisnr, wl = 300, flim = c(2, 10), it = "jpeg", res = 150, osci = TRUE, ovlp = 90)

Inspect spectrograms and throw away image files that are poor quality to prepare for later steps. Make sure you are working in a directory that only has image files associated with this vignette. Delete the image files corresponding to recording 154070 selection 8 and 154070 selection 12, as the start coordinates for these selections are not accurate.

Remove selections with missing image files

# remove selections after deleting corresponding image files
Phae.hisnr2 <- filter_sels(Phae.hisnr, it = "jpeg", incl.wav = TRUE)
nrow(Phae.hisnr2)

After removing the poorest quality selections or signals, there are some other quality control steps that may be helpful.

Check selections

Can selections be read by downstream functions? The function checksels also yields a data frame with columns for duration, minimum samples, sampling rate, channels and bits.

# if selections can be read, "OK" will be printed to check.res column
checksels(Phae.hisnr2, check.header = FALSE)

If selections cannot be read, it is possible the sound files are corrupt. If so, use the fixwavs function to repair wav files.

Tailor temporal coordinates of selections

Sometimes the start and end times of selected signals need fine-tuned adjustments. This is particularly true when signals are found within bouts of closely delivered sounds that may be hard to pull apart, such as duets, or if multiple researchers use different rules-of-thumb to select signals. tailor_sels provides an interactive interface for tailoring the temporal coordinates of selections.

If you check out the image files generated by running spectrograms above, you’ll see that some of the selections made during the automatic detection process with auto_detec do not have accurate start and/or end coordinates.

For instance:

The end of this signal is not well selected.

The temporal coordinates for the tailored signals will be saved in a _ .csv_ file called seltailor_output.csv. You can rename this file and read it back into R to continue downstream analyses.

tailor_sels(Phae.hisnr2, wl = 300, flim = c(2, 10), wn = "hanning", mar = 0.1, osci = TRUE, title = c("sound.files", "selec"), auto.next = TRUE)

# Read in tailor_sels output after renaming the csv file
Phae.hisnrt <- read.csv("Phae_hisnrt.csv", header = TRUE)
str(Phae.hisnrt)

'data.frame':   23 obs. of  6 variables:
 $ sound.files: chr  "Phaethornis-longirostris-154070.wav" "Phaethornis-longirostris-154070.wav" "Phaethornis-longirostris-154070.wav" "Phaethornis-longirostris-154072.wav" ...
 $ selec      : int  14 18 20 36 108 124 142 148 57 83 ...
 $ start      : num  8.66 11.08 12.19 22.6 76.04 ...
 $ end        : num  8.79 11.2 12.32 22.73 76.16 ...
 $ SNR        : num  11.7 11.6 10.2 15.5 15.3 ...
 $ tailored   : chr  "y" "y" "y" "y" ...

Quality control filtering of selections

Find overlapping selections

# To run this example:
# Open Phae_hisnr.csv and modify the start coordinate of the first selection and the end coordinate of the second selection so that the signals overlap

Phae.hisnr <- read.csv("Phae_hisnr.csv", header = TRUE)
str(Phae.hisnr)
head(Phae.hisnr, n = 15)

# yields a data frame with an additional column (ovlp.sels) that indicates which selections overlap
Phae.hisnr <- overlapping_sels(X = Phae.hisnr, max.ovlp = 0)

# run the function again but this time retain only the signals that don't overlap
Phae.hisnr <- overlapping_sels(X = Phae.hisnr, max.ovlp = 0, drop = TRUE)

Make spectrograms of selections

spectrograms(Phae.hisnr, wl = 300, flim = c(2, 10), it = "jpeg", res = 150, osci = TRUE, ovlp = 90)

Remove selections with missing image files

# remove selections after deleting corresponding image files
Phae.hisnr2 <- filter_sels(Phae.hisnr, it = "jpeg", incl.wav = TRUE)
nrow(Phae.hisnr2)

After removing the poorest quality selections or signals, there are some other quality control steps that may be helpful.

Check selections

Can selections be read by downstream functions? The function checksels also yields a data frame with columns for duration, minimum samples, sampling rate, channels and bits.

# if selections can be read, "OK" will be printed to check.res column
checksels(Phae.hisnr2, check.header = FALSE)

If selections cannot be read, it is possible the sound files are corrupt. If so, use the fixwavs function to repair wav files.

Tailor temporal coordinates of selections

For instance:

The end of this signal is not well selected.

The temporal coordinates for the tailored signals will be saved in a _ .csv_ file called seltailor_output.csv. You can rename this file and read it back into R to continue downstream analyses.

tailor_sels(Phae.hisnr2, wl = 300, flim = c(2, 10), wn = "hanning", mar = 0.1, osci = TRUE, title = c("sound.files", "selec"), auto.next = TRUE)

# Read in tailor_sels output after renaming the csv file
Phae.hisnrt <- read.csv("Phae_hisnrt.csv", header = TRUE)
str(Phae.hisnrt)

'data.frame':   23 obs. of  6 variables:
 $ sound.files: chr  "Phaethornis-longirostris-154070.wav" "Phaethornis-longirostris-154070.wav" "Phaethornis-longirostris-154070.wav" "Phaethornis-longirostris-154072.wav" ...
 $ selec      : int  14 18 20 36 108 124 142 148 57 83 ...
 $ start      : num  8.66 11.08 12.19 22.6 76.04 ...
 $ end        : num  8.79 11.2 12.32 22.73 76.16 ...
 $ SNR        : num  11.7 11.6 10.2 15.5 15.3 ...
 $ tailored   : chr  "y" "y" "y" "y" ...

Visual classification of selected signals

Visual classification of signals is fundamental to vocal repertoire analysis, and can also be useful for other questions. If your research focuses on assessing variation between individuals or groups, several warbleR functions can provide you with important information about how to steer your analysis. If there is discrete variation in vocalization structure across groups (e.g. treatments or geographic regions), visual classification of vocalizations will be useful.

Print long spectrograms with `full_spectrograms`

The function full_spectrograms can be used as a tool for visually classifying signals. Long spectrograms can be printed to classify signals by hand, or comments accompanying the selections can be printed over selected signals.

Here, we print the start and end of selections with a red dotted line, and the selection number printed over the signal. If a selection data frame contains a comments column, these will be printed with the selection number.

# highlight selected signals
full_spectrograms(Phae.hisnrt, wl = 300, flim = c(2, 10), ovlp = 10, sxrow = 6, rows = 15, it = "jpeg")

# concatenate full_spectrograms image files into a single PDF per recording
# full_spectrograms images must be jpegs
full_spectrograms2pdf(keep.img = FALSE, overwrite = TRUE)

Check out the image file in your working directory. These will look very similar to the full_spectrograms images produced in vignette 1, but with red dotted lines indicating where the selected signals start and end.

Highlight spectrogram regions with `color_spectro`

color_spectro allows you to highlight selections you’ve made within a short region of a spectrogram. In the example below we will use color_spectro to highlight neighboring songs. This function has a wide variety of uses, and could be especially useful for analysis of duets or coordinated singing bouts. This example is taken directly from the color_spectro documentation. If working with your own data frame of selections, make sure to calculate the frequency range for your selections beforehand using the function frange, which will come up in the next vignette.

# we will use Phaethornis songs and selections from the warbleR package
data(list = c("Phae.long1", "lbh_selec_table"))
writeWave(Phae.long1, "Phae.long1.wav") # save sound files

# subset selection table
# already contains the frequency range for these signals
st <- lbh_selec_table[lbh_selec_table$sound.files == "Phae.long1.wav", ]

# read wave file as an R object
sgnl <- read_sound_file(as.character(st$sound.files[1]))

# create color column
st$colors <- c("red2", "blue", "green")

# highlight selections
color_spectro(wave = sgnl, wl = 300, ovlp = 90, flim = c(1, 8.6), collevels = seq(-90, 0, 5), dB = "B", X = st, col.clm = "colors", base.col = "skyblue", t.mar = 0.07, f.mar = 0.1)

Optimize spectrogram display parameters

spec_param makes a catalog or mosaic of the same signal plotted with different combinations of spectrogram display arguments. The purpose of this function is to help you choose parameters that yield the best spectrograms (e.g. optimal visualization) for your signals (although low signal-to-noise ratio selections may be an exception).

Make lexicons of signals

When we are interested in geographic variation of acoustic signals, we usually want to compare spectrograms from different individuals and sites. This can be challenging when working with large numbers of signals, individuals and/or sites. catalog aims to simplify this task.

This is how it works:

catalog plots a matrix of spectrograms from signals listed in a selection table
the catalog files are saved as image files in the working directory (or path provided)
Several image files are generated if the signals do not fit in a single file
Spectrograms can be labeled or color-tagged to facilitate exploring variation related to the parameter of interest (e.g. site or song type if already classified)
A legend can be added to help match colors with tag levels
- different color palettes can be used for each tag
The duration of the signals can be “fixed” such that all the spectrograms have the same duration
- facilitates comparisons
You can control the number of rows and columns as well as the width and height of the output image

catalog allows you to group signals into biologically relevant groups by coloring the background of selected spectrograms accordingly. There is also an option to add hatching to tag labels, as well as filling the catalog with spectrograms by rows or columns of the selection table data frame, among other additional arguments.

The move_imgs function can come in handy when creating multiple catalogs to avoid overwriting previous image files, or when working through rounds of other image files. In this case, the first catalog we create has signals labeled, tagged and grouped with respective color and hatching levels. The second catalog we create will not have any grouping of signals whatsoever, and could be used for a test of inter-observer reliability. move_imgs helps us move the first catalog into another directory to save it from being overwritten when creating the second catalog.

# create a column of recording IDs for friendlier catalog labels
rec_ID <- sapply(1:nrow(Phae.hisnrt), function(x) {
  gsub(x = strsplit(as.character(Phae.hisnrt$sound.files[x]), split = "-")[[1]][3], pattern = ".wav$", replacement = "")
})
rec_ID

Phae.hisnrt$rec_ID <- rec_ID
str(Phae.hisnrt)

# set color palette
# alpha controls transparency for softer colors
cmc <- function(n) cm.colors(n, alpha = 0.8)

catalog(X = Phae.hisnrt, flim = c(2, 10), nrow = 4, ncol = 3, height = 10, width = 10, tag.pal = list(cmc), cex = 0.8, same.time.scale = TRUE, mar = 0.01, wl = 300, gr = FALSE, labels = "rec_ID", tags = "rec_ID", hatching = 1, group.tag = "rec_ID", spec.mar = 0.4, lab.mar = 0.8, max.group.cols = 5)

catalog2pdf(keep.img = FALSE, overwrite = TRUE)

# assuming we are working from the warbleR_example directory
# the ~/ format does not apply to Windows
# make sure you have already moved or deleted all other pdf files
move_images(from = ".", it = "pdf", create.folder = TRUE, folder.name = "Catalog_image_files")

Catalog with labels, tags and groups

You can also make lexicons for blind scoring, which could be useful for determining interobserver reliability.

# now create a catalog without labels, tags, groups or axes
Phae.hisnrt$no_label <- ""

# catalog(X = Phae.hisnrt, flim = c(1, 10), nrow = 4, ncol = 3, height = 10, width = 10, cex = 0.8, same.time.scale = TRUE, mar = 0.01, wl = 300, spec.mar = 0.4, rm.axes = TRUE, labels = "no_label", lab.mar = 0.8, max.group.cols = 5, img.suffix = "nolabel")

catalog(X = Phae.hisnrt, flim = c(1, 10), nrow = 4, ncol = 3, height = 10, width = 10, tag.pal = list(cmc), cex = 0.8, same.time.scale = TRUE, mar = 0.01, wl = 300, gr = FALSE, labels = "no_label", spec.mar = 0.4, lab.mar = 0.8, max.group.cols = 5, img.suffix = "nolabels")

catalog2pdf(keep.img = FALSE, overwrite = TRUE)

Citation

Please cite warbleR when you use the package:

Araya-Salas, M. and Smith-Vidaurre, G. (2017), warbleR: an R package to streamline analysis of animal acoustic signals. Methods Ecol Evol. 8, 184-191.

Reporting bugs

Please report any bugs here.

Marcelo Araya-Salas, PhD & Grace Smith-Vidaurre

2025-04-21

Bioacoustics in R with `warbleR`

Package repositories

Parallel processing in `warbleR`

Vignette introduction

Prepare for analyses

Obtain example acoustic data from xeno-canto

Filter xeno-canto recordings by quality, signal type and locality

Convert xeno-canto mp3 recordings to wav format

Find overlapping selections

Make spectrograms of selections

Remove selections with missing image files

Check selections

Tailor temporal coordinates of selections

Quality control filtering of selections

Find overlapping selections

Make spectrograms of selections

Remove selections with missing image files

Check selections

Tailor temporal coordinates of selections

Visual classification of selected signals

Print long spectrograms with `full_spectrograms`

Highlight spectrogram regions with `color_spectro`

Optimize spectrogram display parameters

Make lexicons of signals

Citation

Reporting bugs

Visual inspection and signal classification

Marcelo Araya-Salas, PhD & Grace Smith-Vidaurre

2025-04-21

Bioacoustics in R with warbleR

Package repositories

Parallel processing in warbleR

Vignette introduction

Prepare for analyses

Obtain example acoustic data from xeno-canto

Filter xeno-canto recordings by quality, signal type and locality

Convert xeno-canto mp3 recordings to wav format

Find overlapping selections

Make spectrograms of selections

Remove selections with missing image files

Check selections

Tailor temporal coordinates of selections

Quality control filtering of selections

Find overlapping selections

Make spectrograms of selections

Remove selections with missing image files

Check selections

Tailor temporal coordinates of selections

Visual classification of selected signals

Print long spectrograms with full_spectrograms

Highlight spectrogram regions with color_spectro

Optimize spectrogram display parameters

Make lexicons of signals

Citation

Reporting bugs

Bioacoustics in R with `warbleR`

Parallel processing in `warbleR`

Print long spectrograms with `full_spectrograms`

Highlight spectrogram regions with `color_spectro`