Acoustic dissimilarity using dynamic time warping on fundamental frequency contours

ffDTW calculates acoustic dissimilarity of fundamental frequency contours using dynamic time warping. Internally it applies the dtwDist function from the dtw package.

ffDTW(X, wl = 512, length.out = 20, wn = "hanning", ovlp = 70,
bp = c(0, 22), threshold = 5, img = TRUE, parallel = 1, path = NULL,
img.suffix = "ffDTW", pb = TRUE, clip.edges = TRUE, window.type = "none",
open.end = FALSE, scale = FALSE, ...)

Arguments

X	object of class 'selection_table', 'extended_selection_table' or data frame containing columns for sound file name (sound.files), selection number (selec), and start and end time of signal (start and end). The output of `manualoc` or `autodetec` can be used as the input data frame.
wl	A numeric vector of length 1 specifying the window length of the spectrogram, default is 512.
length.out	A numeric vector of length 1 giving the number of measurements of fundamental frequency desired (the length of the time series).
wn	Character vector of length 1 specifying window name. Default is "hanning". See function `ftwindow` for more options.
ovlp	Numeric vector of length 1 specifying % of overlap between two consecutive windows, as in `spectro`. Default is 70.
bp	A numeric vector of length 2 for the lower and upper limits of a frequency bandpass filter (in kHz). Default is c(0, 22).
threshold	amplitude threshold (%) for fundamental frequency detection. Default is 5.
img	Logical argument. If `FALSE`, image files are not produced. Default is `TRUE`.
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.
img.suffix	A character vector of length 1 with a sufix (label) to add at the end of the names of image files. Default is `NULL`.
pb	Logical argument to control progress bar. Default is `TRUE`.
clip.edges	Logical argument to control whether edges (start or end of signal) in which amplitude values above the threshold were not detected will be removed. If `TRUE` (default) this edges will be excluded and signal contour will be calculated on the remaining values. Note that DTW cannot be applied if missing values (e.i. when amplitude is not detected).
window.type	`dtw` windowing control parameter. Character: "none", "itakura", or a function (see `dtw`).
open.end	`dtw` control parameter. Performs open-ended alignments (see `dtw`).
scale	Logical. If `TRUE` fundamental frequency values are z-transformed using the `scale` function, which "ignores" differences in absolute frequencies between the signals in order to focus the comparison in the frequency contour, regardless of the pitch of signals. Default is `TRUE`.
...	Additional arguments to be passed to `trackfreqs` for customizing graphical output.

Value

A matrix with the pairwise dissimilarity values. If img is FALSE it also produces image files with the spectrograms of the signals listed in the input data frame showing the location of the fundamental frequencies.

Details

This function extracts the fundamental frequency values as a time series and then calculates the pairwise acoustic dissimilarity of the selections using dynamic time warping. The function uses the approx function to interpolate values between fundamental frequency measures. If 'img' is TRUE the function also produces image files with the spectrograms of the signals listed in the input data frame showing the location of the fundamental frequencies. Note that if no amplitude is detected at the beginning or end of the signals then NAs will be generated. On the other hand, if amplitude is not detected in between signal segments in which amplitude was detected then the values of this adjacent segments will be interpolated to fill out the missing values (e.g. no NAs in between detected amplitude segments).

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.

Examples