align_test_files: Align test sound files

In baRulho: Quantifying (Animal) Sound Degradation

Align test sound files

Description

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). 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 is TRUE. Can be set globally for the current R session via the "pb" option (see options).
...	Additional arguments to be passed to selection_table for customizing extended selection table.

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.

Value

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

Author(s)

Marcelo Araya-Salas ([e-mail])

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()

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())
}

baRulho documentation built on Sept. 11, 2024, 7:21 p.m.