Align test sound files

align_test_files() aligns test (re-recorded) sound files. It uses the position of acoustic markers found by find_markers() to infer the position of all other sounds referenced in a master sound file, producing an aligned selection table for the re-recorded files.

Usage

align_test_files(
  X,
  Y,
  path = getOption("sound.files.path", "."),
  by.song = TRUE,
  marker = NULL,
  cores = getOption("mc.cores", 1),
  pb = getOption("pb", TRUE),
  ...
)

Arguments

X: Object of class data.frame, selection_table, or extended_selection_table (the last 2 classes are created by warbleR::selection_table() from the warbleR package) with the master sound file annotations. This should be the same data used for finding the position of markers in find_markers(). It should also contain a sound.id column that will be used to label re-recorded sounds according to their counterpart in the master sound file.
Y: Object of class data.frame with the output of find_markers(). This object contains the position of markers in the re-recorded sound files. If more than one marker is supplied for a sound file, only the one with the highest correlation score (scores column in Y) is used.
path: Character string containing the directory path where test (re-recorded) sound files are found.
by.song: Logical argument to indicate if the extended selection table should be created by song (see the by.song argument of warbleR::selection_table()). Default TRUE.
marker: Character string to define whether a "start" or "end" marker would be used for aligning re-recorded sound files. Default NULL. Deprecated.
cores: Numeric vector of length 1. Controls whether parallel computing is applied by specifying the number of cores to be used. Default 1 (i.e. no parallel computing). Can be set globally for the current R session via the "mc.cores" option (see options()).
pb: Logical argument to control if progress bar is shown. Default TRUE. Can be set globally for the current R session via the "pb" option (see options()).
...: Additional arguments to be passed to warbleR::selection_table() for customizing the extended selection table.

Value

An object of the same class as X with the aligned sounds from the test (re-recorded) sound files.

Details

The function aligns sounds found in re-recorded sound files (referenced in Y) according to a master sound file (referenced in X). If more than one marker is supplied for a sound file only the one with the highest correlation score (scores column in Y) is used. The function outputs an extended selection table by default.

References

Araya-Salas, M., Grabarczyk, E. E., Quiroz-Oliva, M., Garcia-Rodriguez, A., & Rico-Guevara, A. (2025). Quantifying degradation in animal acoustic signals with the R package baRulho. Methods in Ecology and Evolution, 00, 1-12. https://doi.org/10.1111/2041-210X.14481

Author

Marcelo Araya-Salas (marcelo.araya@ucr.ac.cr)

Examples

{
  # load example data
  data(list = c("master_est", "test_sounds_est"))

  # save example files in working director to recreate a case in which working
  # with sound files instead of extended selection tables.
  # This doesn't have to be done with your own data as you will
  # have them as sound files already.
  for (i in unique(test_sounds_est$sound.files)[1:2]) {
    writeWave(object = attr(test_sounds_est, "wave.objects")[[i]], 
              file.path(tempdir(), i))
  }

  # save master file
  writeWave(object = attr(master_est, "wave.objects")[[1]], 
        file.path(tempdir(), "master.wav"))

  # get marker position for the first test file
    markers <- find_markers(X = master_est,
    test.files = unique(test_sounds_est$sound.files)[1],
    path = tempdir())

  # align all test sounds
  alg.tests <- align_test_files(X = master_est, Y = markers, 
  path = tempdir())
}
#> computing correlations (step 1 of 0):
#> all selections are OK 
#>