Handling extended selection tables

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

is_extended_selection_table(est)

[1] TRUE

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

est2 <- est[1:2, ]

is_extended_selection_table(est2)

[1] TRUE

As shown above, there is also a generic version of print() for this class of objects:

## print (equivalent to `print(est)`)
est

Object of class 'extended_selection_table'
* The output of the following call:
selection_table(X = lbh_selec_table, path = tempdir(), extended = TRUE,  pb = FALSE)

Contains: 
*  A selection table data frame with 11 row(s) and 7 columns:
|sound.files      | channel| selec| start|   end| bottom.freq|
|:----------------|-------:|-----:|-----:|-----:|-----------:|
|Phae.long1.wav_1 |       1|     1|   0.1| 0.273|        2.22|
|Phae.long1.wav_2 |       1|     1|   0.1| 0.263|        2.17|
|Phae.long1.wav_3 |       1|     1|   0.1| 0.275|        2.22|
|Phae.long2.wav_1 |       1|     1|   0.1| 0.233|        2.32|
|Phae.long2.wav_2 |       1|     1|   0.1| 0.226|        2.28|
|Phae.long3.wav_1 |       1|     1|   0.1| 0.231|        3.01|
... 1 more column(s) (top.freq)
 and 5 more row(s)

* 11 wave object(s) (as attributes): 
Phae.long1.wav_1, Phae.long1.wav_2, Phae.long1.wav_3, Phae.long2.wav_1, Phae.long2.wav_2, Phae.long3.wav_1
... and 5 more

* A data frame (check.results) with 11 rows generated by check_sels() (as attribute)

The selection table was created by element (see 'class_extended_selection_table')
* 1 sampling rate(s) (in kHz): 22.5
* 1 bit depth(s): 16
* Created by warbleR 1.1.33

You can also split them and/or combine them by rows. Here the original extended_selection_table is divided using indexing into two objects and combine the two back into a single object using rbind():

est3 <- est[1:5, ]

est4 <- est[6:11, ]

est5 <- rbind(est3, est4)

# print
est5

Object of class 'extended_selection_table'
* The output of the following call:
rbind(deparse.level, ..1, ..2)

Contains: 
*  A selection table data frame with 11 row(s) and 7 columns:
|sound.files      | channel| selec| start|   end| bottom.freq|
|:----------------|-------:|-----:|-----:|-----:|-----------:|
|Phae.long1.wav_1 |       1|     1|   0.1| 0.273|        2.22|
|Phae.long1.wav_2 |       1|     1|   0.1| 0.263|        2.17|
|Phae.long1.wav_3 |       1|     1|   0.1| 0.275|        2.22|
|Phae.long2.wav_1 |       1|     1|   0.1| 0.233|        2.32|
|Phae.long2.wav_2 |       1|     1|   0.1| 0.226|        2.28|
|Phae.long3.wav_1 |       1|     1|   0.1| 0.231|        3.01|
... 1 more column(s) (top.freq)
 and 5 more row(s)

* 11 wave object(s) (as attributes): 
Phae.long1.wav_1, Phae.long1.wav_2, Phae.long1.wav_3, Phae.long2.wav_1, Phae.long2.wav_2, Phae.long3.wav_1
... and 5 more

* A data frame (check.results) with 11 rows generated by check_sels() (as attribute)

The selection table was created by element (see 'class_extended_selection_table')
* 1 sampling rate(s) (in kHz): 22.5
* 1 bit depth(s): 16
* Created by warbleR 1.1.33

The resulting extended selection table contains the same data as the original extended selection table:

# same annotations
all.equal(est, est5, check.attributes = FALSE)

[1] TRUE

# same acoustic data
all.equal(attr(est, "wave.objects"), attr(est5, "wave.objects"))

[1] TRUE

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

wv1 <- read_sound_file(X = est, 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 

# print spectrogram
seewave::spectro(
  wv1,
  wl = 150,
  grid = FALSE,
  scale = FALSE,
  ovlp = 90,
  palette = viridis::viridis,
  collevels = seq(-100, 0 , 5)
)

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

for (i in 1:6) {
  wv <- read_sound_file(
    X = est,
    index = i,
    from = 0.05,
    to = 0.32
  )
  
  seewave::spectro(
    wv,
    wl = 150,
    grid = FALSE,
    scale = FALSE,
    axisX = FALSE,
    axisY = FALSE,
    ovlp = 90,
    palette = viridis::viridis,
    collevels = seq(-100, 0 , 5)
  )
}

The read_sound_file() function requires a 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 frame
Y <-
  data.frame(
    sound.files = est$sound.files,
    site = "La Selva",
    lek = c(rep("SUR", 5), rep("CCL", 6))
  )

# combine
mrg_est <- merge(est, Y, by = "sound.files")

# check class
is_extended_selection_table(mrg_est)

[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 est
mrg_est <- fix_extended_selection_table(X = mrg_est, Y = est)

# check class
is_extended_selection_table(mrg_est)

[1] TRUE

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

Finally, these objects can be used as input for most warbleR functions, without the need of refering to any sound file. For instance we can easily measure acoustic parameters on data in extended_selection_table format using the function spectro_analysis():

#  parametros espectrales
sp <- spectro_analysis(est)

# check first 10 columns
sp[, 1:10]

‘By element’ vs ‘by song’ extended selection tables

As mention above extended selection tables by default contain one wave object for each annotation (i.e. row):

length(attr(est, "wave.objects")) == length(unique(paste(est$sound.files)))

[1] TRUE

This default behavior generates a ‘by element’ extended selection table, as each resulting wave object contains a single element (usually defined as continuous traces of power spectral entropy in the spectrograms). Acoustic signals can have structure above the basic signal units (elements), like in long repertoire songs or multi-syllable calls, in which elements are always broadcast as a sequences, often with consistent order and timing. It is then desirable to keep information about the relative position of elements in these sequences. However,‘by element’ extended selection tables discards some element sequence information. This can be overwritten using the argument by.song, which allows to keep in a single wave object all the elements belonging to the same ‘song’. In this case song refers to any grouping of sounds above the ‘element’ level.

The song of the Scale-throated Hermit (Phaethornis eurynome) will be used to show how this can be done. This song consists of a sequence of two elements, which are separated by short gaps:

Annotated spectrogram of Scale-throated Hermit songs. Vertical orange lines highlight songs while skyblue boxes show the frequency-time position of individual elements. The sound file can be found at https://xeno-canto.org/15607.

An example sound file with this species’ song can be downloaded as follows (the sound file can also be downloaded manually from this link):

# load data
data("sth_annotations")

# download sound file from Xeno-Canto using catalog id
out <-
  query_xc(qword = "nr:15607",
           download = TRUE,
           path = tempdir())

# check file is found in temporary directory
list.files(path = tempdir(), "mp3")

[1] "Phaethornis-eurynome-15607.mp3"

warbleR comes with an example data set containing annotations on this sound file, which can be loaded like this:

# load  Scale-throated Hermit example annotations
data("sth_annotations")

Note that these annotations contain an additional column called ‘song’, with the song ID labels for elements (rows) belonging to the same song:

# print into the console
head(sth_annotations)

These data (annotations + sound file) can be used to create a ‘by song’ extended selection table. To do this the name of the column containing the ‘song’ level labels must be supplied to the argument ‘by.song’:

# create by song extended selection table
bs_est <-
  selection_table(X = sth_annotations,
                  extended = TRUE,
                  by.song = "song", 
                  path = tempdir())

all selections are OK 

In a ‘by song’ extended selection table there are as many wave objects as songs in our annotation data:

length(attr(bs_est, "wave.objects")) == length(unique(paste(bs_est$sound.files, bs_est$song)))

[1] TRUE

We can extract an entire wave object to check that two elements are actually included:

# extract wave object
wave_song1 <-
  read_sound_file(
    X = bs_est,
    index = 1,
    from = 0,
    to = Inf
  )

# plot spectro
seewave::spectro(
  wave_song1,
  wl = 150,
  grid = FALSE,
  scale = FALSE,
  ovlp = 90,
  palette = viridis::viridis,
  collevels = seq(-100, 0 , 5),
  flim = c(1, 12)
)

Note that ‘by song’ extended selection tables can be converted into ‘by element’ tables using the function by_element_est().

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. First, 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:

# create long selection table
lng.selec.table <- do.call(rbind, replicate(10, lbh_selec_table,
                                            simplify = FALSE))

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

# create extended selection table
lng_est <- selection_table(X = lng.selec.table,
                           pb = FALSE,
                           extended = TRUE)


# load packages
library(microbenchmark)
library(ggplot2)

# check performance
mbmrk.snr <- microbenchmark(
  extended = sig2noise(lng_est,
                       mar = 0.05),
  regular = sig2noise(lng.selec.table,
                      mar = 0.05),
  times = 50
)

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

autodetec image example

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 computing overhead).

Sharing acoustic data

This new object class allows to share complete data sets, including acoustic data. To do this we can make use of the RDS file format to save extended selection tables. These files can be easily shared with others, allowing to share a entire acoustic data set in a single file, something that can be tricky when dealing with acoustic data. For example, the following code downloads an extended selection table of inquiry calls from Spix’s disc-winged bats used in Araya-Salas et al (2020) (it can take a few minutes! Can also be manually downloaded from here):

URL <- "https://figshare.com/ndownloader/files/21167052"

options(timeout = max(300, getOption("timeout")))

download.file(
  url = URL,
  destfile = file.path(tempdir(), "est_inquiry.RDS"),
  method = "auto"
)

est <- readRDS(file.path(tempdir(), "est_inquiry.RDS"))

nrow(est)

[1] 336

This data is ready to be used. For instance, here I create a multipanel graph with the spectrograms of the first 6 selections:

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

for (i in 1:6) {
  wv <- read_sound_file(
    X = est,
    index = i,
    from = 0.05,
    to = 0.17
  )
  
  spectro(
    wv,
    grid = FALSE,
    scale = FALSE,
    axisX = FALSE,
    axisY = FALSE,
    ovlp = 90,
    flim = c(10, 50),
    palette = viridis::viridis,
    collevels = seq(-100, 0 , 5)  
    )
}

We can also measured pairwise cross correlation (for simplicity only on the first 4 rows):

xcorr_inquiry <- cross_correlation(est[1:4, ])

xcorr_inquiry