Introduction to warbleR

Extended selection tables

When the extended = TRUE argument the function generates an object of the extended_selection_table class that also contains a list of ‘wave’ objects corresponding to each of the selections in the data. Therefore, the function transforms the selection table into self-contained objects since the original sound files are no longer needed to perform most of the acoustic analysis in warbleR. This can greatly facilitate the storage and exchange of (bio)acoustic data. In addition, it also speeds up analysis, since it is not necessary to read the sound files every time the data is analyzed.

Now, as mentioned earlier, you need the selection_table() function to create an extended selection table. You must also set the argument extended = TRUE (otherwise, the class would be a selection table). The following code converts the sample data into an extended selection table:

#  global parameters
warbleR_options(wav.path = "./examples")

ext_st <- selection_table(X = lbh_selec_table, pb = FALSE, 
          extended = TRUE, confirm.extended = FALSE)

all selections are OK 

And that is. Now the acoustic data and the selection data (as well as the additional metadata) are all together in a single R object.

Handling extended selection tables

Several functions can be used to deal with objects of this class. You can test if the object belongs to the extended_selection_table:

is_extended_selection_table(ext_st)

[1] TRUE

You can subset the selection in the same way that any other data frame and it will still keep its attributes:

ext_st2 <- ext_st[1:2, ]

is_extended_selection_table(ext_st2)

[1] TRUE

There is also a generic version of print() for this class of objects:

## print
print(ext_st)

object of class 'extended_selection_table' 
 contains a selection table data frame with 11 rows and 9 columns: 
       sound.files channel selec start       end bottom.freq top.freq sel.comment rec.comment
1 Phae.long1.wav_1       1     1   0.1 0.2730334    2.220105 8.604378         c24          NA
2 Phae.long1.wav_2       1     1   0.1 0.2630480    2.169437 8.807053         c25          NA
3 Phae.long1.wav_3       1     1   0.1 0.2749187    2.218294 8.756604         c26          NA
4 Phae.long2.wav_1       1     1   0.1 0.2325709    2.316862 8.822316         c27          NA
5 Phae.long2.wav_2       1     1   0.1 0.2261502    2.284006 8.888027         c28          NA
6 Phae.long3.wav_1       1     1   0.1 0.2312195    3.006834 8.822316         c29          NA
... and 5 more rows 
11 wave objects (as attributes): 
[1] "Phae.long1.wav_1" "Phae.long1.wav_2" "Phae.long1.wav_3" "Phae.long2.wav_1" "Phae.long2.wav_2"
[6] "Phae.long3.wav_1"
... and 5 more 
and a data frame (check.results) generated by check_sels() (as attribute) 
the selection table was created by element (see 'class_extended_selection_table') 
1 sampling rate(s): 22.5 
1 bit depth(s): 16 
created by warbleR 1.1.24

… which is equivalent to:

ext_st

object of class 'extended_selection_table' 
 contains a selection table data frame with 11 rows and 9 columns: 
       sound.files channel selec start       end bottom.freq top.freq sel.comment rec.comment
1 Phae.long1.wav_1       1     1   0.1 0.2730334    2.220105 8.604378         c24          NA
2 Phae.long1.wav_2       1     1   0.1 0.2630480    2.169437 8.807053         c25          NA
3 Phae.long1.wav_3       1     1   0.1 0.2749187    2.218294 8.756604         c26          NA
4 Phae.long2.wav_1       1     1   0.1 0.2325709    2.316862 8.822316         c27          NA
5 Phae.long2.wav_2       1     1   0.1 0.2261502    2.284006 8.888027         c28          NA
6 Phae.long3.wav_1       1     1   0.1 0.2312195    3.006834 8.822316         c29          NA
... and 5 more rows 
11 wave objects (as attributes): 
[1] "Phae.long1.wav_1" "Phae.long1.wav_2" "Phae.long1.wav_3" "Phae.long2.wav_1" "Phae.long2.wav_2"
[6] "Phae.long3.wav_1"
... and 5 more 
and a data frame (check.results) generated by check_sels() (as attribute) 
the selection table was created by element (see 'class_extended_selection_table') 
1 sampling rate(s): 22.5 
1 bit depth(s): 16 
created by warbleR 1.1.24

You can also join them in rows. Here the original extended_selection_table is divided into 2 and bound again using rbind():

ext_st3 <- ext_st[1:5, ]

ext_st4 <- ext_st[6:11, ]

ext_st5 <- rbind(ext_st3, ext_st4)

#print
ext_st5

object of class 'extended_selection_table' 
 contains a selection table data frame with 11 rows and 9 columns: 
       sound.files channel selec start       end bottom.freq top.freq sel.comment rec.comment
1 Phae.long1.wav_1       1     1   0.1 0.2730334    2.220105 8.604378         c24          NA
2 Phae.long1.wav_2       1     1   0.1 0.2630480    2.169437 8.807053         c25          NA
3 Phae.long1.wav_3       1     1   0.1 0.2749187    2.218294 8.756604         c26          NA
4 Phae.long2.wav_1       1     1   0.1 0.2325709    2.316862 8.822316         c27          NA
5 Phae.long2.wav_2       1     1   0.1 0.2261502    2.284006 8.888027         c28          NA
6 Phae.long3.wav_1       1     1   0.1 0.2312195    3.006834 8.822316         c29          NA
... and 5 more rows 
11 wave objects (as attributes): 
[1] "Phae.long1.wav_1" "Phae.long1.wav_2" "Phae.long1.wav_3" "Phae.long2.wav_1" "Phae.long2.wav_2"
[6] "Phae.long3.wav_1"
... and 5 more 
and a data frame (check.results) generated by check_sels() (as attribute) 
the selection table was created by element (see 'class_extended_selection_table') 
1 sampling rate(s): 22.5 
1 bit depth(s): 16 
created by warbleR 1.1.24

# are they equal?
all.equal(ext_st, ext_st5)

[1] TRUE

The ‘wave’ objects can be read individually using read_wave(), a wrapper for the readWave() function of tuneR, which can handle extended selection tables:

wv1 <- read_wave(X = ext_st, index = 3, from = 0, to = 0.37)

These are regular ‘wave’ objects:

class(wv1)

[1] "Wave"
attr(,"package")
[1] "tuneR"

wv1

Wave Object
    Number of Samples:      8325
    Duration (seconds):     0.37
    Samplingrate (Hertz):   22500
    Channels (Mono/Stereo): Mono
    PCM (integer format):   TRUE
    Bit (8/16/24/32/64):    16 

spectro(wv1, wl = 150, grid = FALSE, scale = FALSE, ovlp = 90)

par(mfrow = c(3, 2), mar = rep(0, 4))

for(i in 1:6){
  
  wv <- read_wave(X = ext_st, index = i, from = 0.05, to = 0.32)

  spectro(wv, wl = 150, grid = FALSE, scale = FALSE, axisX = FALSE,
          axisY = FALSE, ovlp = 90)

}

The read_wave() function requires the selection table, as well as the row index (i.e. the row number) to be able to read the ‘wave’ objects. It can also read a regular ‘wave’ file if the path is provided.

Note that other functions that modify data frames are likely to delete the attributes in which the ‘wave’ objects and metadata are stored. For example, the merge and the extended selection box will remove its attributes:

# create new data base
Y <- data.frame(sound.files = ext_st$sound.files, site = "La Selva", lek = c(rep("SUR", 5), rep("CCL", 6)))

# combine
mrg_ext_st <- merge(ext_st, Y, by = "sound.files")

# check class
is_extended_selection_table(mrg_ext_st)

[1] FALSE

In this case, we can use the fix_extended_selection_table() function to transfer the attributes of the original extended selection table:

# fix
mrg_ext_st <- fix_extended_selection_table(X = mrg_ext_st, Y = ext_st)

# check class
is_extended_selection_table(mrg_ext_st)

[1] TRUE

This works as long as some of the original sound files are retained and no other selections are added.

& nbsp;

Selection table size

The size of the extended selection box will depend on the number of selections, the sampling rate, the duration of the selection and the length of margins (i.e. additional time you want to keep on each side of the selection). In this example, a selection table with 1000 selections is created simply by repeating the sample data frame several times and then is converted to an extended selection table:

lng.selec.table <- do.call(rbind, replicate(100, lbh_selec_table, 
                        simplify = FALSE))[1:1000,]

lng.selec.table$selec <- 1:nrow(lng.selec.table)

nrow(lng.selec.table)

lng_ext_st <- selection_table(X = lng.selec.table, pb = FALSE, 
                        extended = TRUE, confirm.extended = FALSE)

lng_ext_st

all selections are OK 

object of class 'extended_selection_table' 
 contains a selection table data frame with 1000 rows and 9 columns: 
       sound.files channel selec start       end bottom.freq top.freq sel.comment rec.comment
1 Phae.long1.wav_1       1     1   0.1 0.2730334    2.220105 8.604378         c24          NA
2 Phae.long1.wav_2       1     1   0.1 0.2630480    2.169437 8.807053         c25          NA
3 Phae.long1.wav_3       1     1   0.1 0.2749187    2.218294 8.756604         c26          NA
4 Phae.long2.wav_4       1     1   0.1 0.2325709    2.316862 8.822316         c27          NA
5 Phae.long2.wav_5       1     1   0.1 0.2261502    2.284006 8.888027         c28          NA
6 Phae.long3.wav_6       1     1   0.1 0.2312195    3.006834 8.822316         c29          NA
... and 994 more rows 
1000 wave objects (as attributes): 
[1] "Phae.long1.wav_1" "Phae.long1.wav_2" "Phae.long1.wav_3" "Phae.long2.wav_4" "Phae.long2.wav_5"
[6] "Phae.long3.wav_6"
... and 994 more 
and a data frame (check.results) generated by check_sels() (as attribute) 
the selection table was created by element (see 'class_extended_selection_table') 
1 sampling rate(s): 22.5 
1 bit depth(s): 16 
created by warbleR 1.1.24

format(object.size(lng_ext_st), units = "auto")

[1] "31.4 Mb"

As you can see, the object size is only ~ 31 MB. Then, as a guide, a selection box with 1000 selections similar to those of ‘lbh_selec_table’ (average duration of ~ 0.15 seconds) at a sampling rate of 22.5 kHz and the default margin (mar = 0.1) will generate an extended selection box ~ 31 MB or ~ 310 MB for a selection table of 10,000 rows.

Analysis using extended selection tables

These objects can be used as input for most warbleR functions. Here are some examples of warbleR functions using extended_selection_table:

#  spectrographic parameters
sp <- specan(ext_st)

sp

snr <- sig2noise(ext_st, mar = 0.05)

snr

dtw.dist <- dfDTW(ext_st, img = FALSE)

dtw.dist

measuring dominant frequency contours (step 1 of 2):
measuring dominant frequency:calculating DTW distances (step 2 of 2, no progress bar):

Performance

The use of extended_selection_table objects can improve performance (in our case, measured as time). Here we use microbenchmark to compare the performance of sig2noise() and ggplot2 to plot the results:

# load packages
library(microbenchmark)
library(ggplot2)

# take first 100 selections
mbmrk.snr <- microbenchmark(extended = sig2noise(lng_ext_st[1:100, ], 
      mar = 0.05), regular = sig2noise(lng.selec.table[1:100, ], 
                    mar = 0.05), times = 50)

autoplot(mbmrk.snr) + ggtitle("sig2noise")

Coordinate system already present. Adding new coordinate system, which will replace the existing one.

The function runs much faster in the extended selection tables. Performance gain is likely to improve when longer recordings and data sets are used (that is, to compensate for computer overload).

Create selections ‘by song’

The extended selection above were made by element. That is, each sound file within the object contains a single selection (that is, a 1: 1 correspondence between the selections and the ‘wave’ objects). However, extended selection tables can also be created using a higher hierarchical level with the argument by.song. In this case, “song” represents a higher level that contains one or more selections and that the user may want to keep together for a particular analysis (for example, the duration of the intervals). The by.song argument takes the name of the column of characters or factors with the IDs of the different" songs "within a sound file (note that the function assumes that a given song can only be found in only one sound file, so the selections with the same song ID, but from different sound files are taken as different ‘songs’).

To create a selection table by song, let’s add an artificial song column to our example data in which each of the sound files has 2 songs:

# add column
lbh_selec_table$song <- c(1, 1, 2, 1, 2, 1, 1, 2, 1, 2, 2)

The data looks like this:

Now we can create an extended selection table ‘by song’ using the column name ‘song’ as input for the argument by.song:

bs_ext_st <- selection_table(X = lbh_selec_table, extended = TRUE,
                              confirm.extended = FALSE, by.song = "song")

checking selections (step 1 of 2):
all selections are OK 
saving wave objects into extended selection table (step 2 of 2):

In this case, we should only have 8 ‘wave’ objects instead of 11 as when the object was created ‘by selection’:

# by element
length(attr(ext_st, "wave.objects"))

[1] 11

# by song
length(attr(bs_ext_st, "wave.objects"))

[1] 8

Again, these objects can also be used in any analyzes:

# signal to noise ratio
bs_snr <- sig2noise(bs_ext_st, mar = 0.05)

Sharing acoustic data

This new object class allows to share complete data sets, including acoustic data. For example, the following code downloads a subset of the data used in Araya-Salas et al (2017) (can also be downloaded from here):

URL <- "https://marceloarayasalas.weebly.com/uploads/2/5/5/2/25524573/extended.selection.table.araya-salas.et.al.2017.bioacoustics.100.sels.rds"

dat <- readRDS(gzcon(url(URL)))

nrow(dat)

[1] 100

format(object.size(dat), units = "auto")

[1] "10.1 Mb"

The total size of the 100 sound files from which these selections were taken adds up to 1.1 GB. The size of the extended selection table is only 10.1 MB.

This data is ready to be used:

sp <- specan(dat, bp = c(2, 10))

head(sp)

… and the spectrograms can be visualized as follows:

par(mfrow = c(3, 2), mar = rep(0, 4))

for(i in 1:6){
  
  wv <- read_wave(X = dat, index = i, from = 0.17, to = 0.4)

  spectro(wv, wl = 250, grid = FALSE, scale = FALSE, axisX = FALSE,
          axisY = FALSE, ovlp = 90, flim = c(0, 12), 
          palette = reverse.gray.colors.1)
}

The NatureSounds package contains an extended selection table with long-billed hermit hummingbirds vocalizations from 10 different song types:

data("Phae.long.est")

Phae.long.est

object of class 'extended_selection_table' 
 contains a selection table data frame with 50 rows and 8 columns: 
  sound.files selec start     end bottom.freq top.freq lek lek.song.type
1    BR2-A1-1     1   0.1 0.26761      1.6020   10.952 BR2        BR2-A1
2    BR2-A1-2     1   0.1 0.26521      1.8914   11.025 BR2        BR2-A1
3    BR2-A1-3     1   0.1 0.27162      1.7177   11.025 BR2        BR2-A1
4    BR2-A1-4     1   0.1 0.27009      1.8335   11.025 BR2        BR2-A1
5    BR2-A1-5     1   0.1 0.27697      2.1229   11.025 BR2        BR2-A1
6    CCE-I3-1     1   0.1 0.24899      1.7551   11.025 CCE        CCE-I3
... and 44 more rows 
50 wave objects (as attributes): 
[1] "BR2-A1-1" "BR2-A1-2" "BR2-A1-3" "BR2-A1-4" "BR2-A1-5" "CCE-I3-1"
... and 44 more 
and a data frame (check.results) generated by check_sels() (as attribute) 
the selection table was created by element (see 'class_extended_selection_table') 
1 sampling rate(s): 22.05 
1 bit depth(s): 8 
created by warbleR < 1.1.21

table(Phae.long.est$lek.song.type)

BR2-A1 CCE-I3 LOC-D1 SAT-F1 STR-A2 SUR-E1 SUR-K4 TR1-C2 TR1-C5 TR1-D4 
     5      5      5      5      5      5      5      5      5      5 

The ability to compress large data sets and the ease of performing analyzes that require a single R object can simplify the exchange of data and the reproducibility of bioacoustic analyzes.

Get and prepare recordings

The querxc() 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.

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:

Automatic detections

Automatic detection can significantly speed up acoustic analysis. warbleR offers two main methods for automatic signal detection (cross-correlation and amplitude threshold filter) as well as functions to explore detections:

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:

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:

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.

Visually inspection of annotations and measurements

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: