warbleR (version 1.1.7)

dfDTW: Acoustic dissimilarity using dynamic time warping on dominant frequency contours

Description

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

Usage

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

Arguments

X

Data frame with results containing columns for sound file name (sound.files), selection number (selec), and start and end time of signal (start and end). The ouptut 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 character vector of length 1 giving the number of measurements of dominant 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 dominant 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). Not availble in Windows OS.

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 suffix (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. Note that progress bar is only used when parallel = 1.

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 remainging 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 dominant 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 dominant frequencies.

Details

This function extracts the dominant frequency values as a time series and then calculates the pairwise acoustic dissimilarity using dynamic time warping. The function uses the approx function to interpolate values between dominant 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 dominant frequencies.

See Also

specreator for creating spectrograms from selections, snrspecs for creating spectrograms to optimize noise margins used in sig2noise and dfts, ffts, ffDTW for frequency contour overlaid spectrograms. https://marce10.github.io/2016-09-12-Similarity_of_acoustic_signals_with_dynamic_time_warping_(DTW)/ Other spectrogram.creators: dfts, ffDTW, ffts, snrspecs, sp.en.ts, specreator, trackfreqs

Examples

## Not run: ------------------------------------
# # set the temp directory
# setwd(tempdir())
# 
# #load data
# data(list = c("Phae.long1", "Phae.long2","selec.table"))
# writeWave(Phae.long2, "Phae.long2.wav") #save sound files 
# writeWave(Phae.long1, "Phae.long1.wav")
# 
# # run function 
# dfDTW(selec.table, length.out = 30, flim = c(1, 12), bp = c(2, 9), wl = 300)
# 
## ---------------------------------------------