Skip to contents

Pairwise similarity of waveforms

Source: R/waveform_similarity.R
waveform_similarity.Rd

waveform_similarity estimates the similarity of two sound waveforms

Usage

waveform_similarity(
  X = NULL,
  wl = 512,
  bp = "pairwise.freq.range",
  ovlp = 70,
  sim.method = "correlation",
  type = "standard",
  parallel = 1,
  path = NULL,
  pb = TRUE,
  n = 100
)

Arguments

X

'selection_table', 'extended_selection_table' or data frame containing columns for sound files (sound.files), selection number (selec), and start and end time of signal (start and end). All selections must have the same sampling rate.

wl

A numeric vector of length 1 specifying the window length of the spectrogram, default is 512. Only used when applying a bandpass filter bp != NULL.

bp

A numeric vector of length 2 for the lower and upper limits of a frequency bandpass filter (in kHz). If columns for bottom and top frequency ('bottom.freq' and 'top.freq') are supplied "pairwise.freq.range" can be used (default). If so, the lowest values in 'bottom.freq' and the highest values in 'top.freq' for the selections involved in a pairwise comparison will be used as bandpass limits.

ovlp

Numeric vector of length 1 specifying % of overlap between two consecutive windows, as in spectro. Default is 70. High values of overlap slow down the function. Only used when applying a bandpass filter bp != NULL.

sim.method

A character vector of length 1 specifying the similarity method. Two option are available:

  • "correlation": calculates the Pearson correlation between the waveforms of the two signals. Higher values indicate higher similarity.

  • "DTW": calculates the Dynamic Time Warping distance between the waveforms of the two signals. Lower values indicate higher similarity.

type

A character vector of length 1 specifying the approach for estimating similarity. Two option are available:

  • "standard": estimates the similarity between the two waveforms with a single point estimate (e.g. the correlation or DTW distance between them).

  • "sliding": estimates the similarity between the two waveforms by calculating the correlation or DTW distance at each "sliding" step of the spectrogram of the shortest selection over the longest one. This approach is more computationally intensive but might be more appropriate when comparing sounds with large differences in duration or when the appropriate alignment of the waveforms is hard to determine.

parallel

Numeric. Controls whether parallel computing is applied. It specifies the number of cores to be used. Default is 1 (i.e. no parallel computing).

path

Character string containing the directory path where the sound files are located. If NULL (default) then the current working directory is used.

pb

Logical argument to control progress bar. Default is TRUE.

n

Numeric. Number of values used to represent each waveform. Default is 100. Note that both waveforms are forced to have the same length which is done by interpolating amplitude values using the function approx.

Value

The function returns a matrix with the similarity for each pairwise comparison.

Details

This function calculates the pairwise similarity of multiple waveforms referenced in a selection table. Both waveforms are forced to have the same length (see argument 'n'). This is done by interpolating amplitude values using the function approx. The function can be used to compare waveforms using either the correlation coefficient or the Dynamic Time Warping distance. The latter is a measure of similarity between two sequences that may vary in the timing of occurrence of the changes in amplitude. Make sure all sound files have the same sampling rate (can be checked with check_sels or check_sound_files).

References

Araya-Salas, M., & Smith-Vidaurre, G. (2017). warbleR: An R package to streamline analysis of animal acoustic signals. Methods in Ecology and Evolution, 8(2), 184-191.H. Khanna, S.L.L. Gaunt & D.A. McCallum (1997). Digital spectrographic cross-correlation: tests of sensitivity. Bioacoustics 7(3): 209-234Lyon, R. H., & Ordubadi, A. (1982). Use of cepstra in acoustical signal analysis. Journal of Mechanical Design, 104(2), 303-306.

See also

cross_correlation, spectro_analysis, freq_DTW

Author

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

Examples

{
  # load data
  data(list = c("Phae.long1", "Phae.long2", "Phae.long3", "Phae.long4", "lbh_selec_table"))

  # save sound files
  writeWave(Phae.long1, file.path(tempdir(), "Phae.long1.wav"))
  writeWave(Phae.long2, file.path(tempdir(), "Phae.long2.wav"))
  writeWave(Phae.long3, file.path(tempdir(), "Phae.long3.wav"))
  writeWave(Phae.long4, file.path(tempdir(), "Phae.long4.wav"))

  # run waveform correlation
  wcor <- waveform_similarity(X = lbh_selec_table, path = tempdir())
}