Align test sound files

align_test_files aligns test (re-recorded) sound 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 the function selection_table from the warbleR package). This should be the same data than that was 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 'X') 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 'by.song' selection_table argument). Default is TRUE.

marker

Character string to define whether a "start" or "end" marker would be used for aligning re-recorded sound files. Default is NULL. DEPRECATED.

cores

Numeric vector of length 1. Controls whether parallel computing is applied by specifying the number of cores to be used. Default is 1 (i.e. no parallel computing).

pb

Logical argument to control if progress bar is shown. Default is TRUE.

...

Additional arguments to be passed to selection_table for customizing extended selection table.

Value

An object of the same class than 'X' with the aligned sounds from 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 'X') is used. The function outputs an 'extended selection table' by default.

References

Araya-Salas M., E. Grabarczyk, M. Quiroz-Oliva, A. Garcia-Rodriguez, A. Rico-Guevara. (2023), baRulho: an R package to quantify degradation in animal acoustic signals .bioRxiv 2023.11.22.568305.

See also

manual_realign; find_markers; plot_aligned_sounds

Other test sound alignment: auto_realign(), find_markers(), manual_realign(), plot_aligned_sounds()

Author

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

Examples

{
  # load example data
  data("master_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())
}
#> running cross-correlation (step 1 out of 2):
#> running peak detection (step 2 out of 2):
#> Aligning test sound files (step 1 out of 2):
#> Creating extended selection table (step 2 out of 2):
#> checking selections (step 1 of 2):
#> saving wave objects into extended selection table (step 2 of 2):