ffDTW: Acoustic dissimilarity using dynamic time warping on fundamental frequency contours

Description

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

Usage

ffDTW(X, wl = 512, flim = c(0, 22), length.out = 20, wn = "hanning", pal = reverse.gray.colors.2, ovlp = 70, inner.mar = c(5, 4, 4, 2), outer.mar =  c(0, 0, 0, 0), picsize = 1, res = 100, cexlab = 1, title = TRUE, propwidth = FALSE,  xl = 1, gr = FALSE, sc = FALSE, bp = c(0, 22), cex = 1,  threshold = 15, col = "red2", pch = 16,  mar = 0.05,  lpos = "topright", it = "jpeg", img = TRUE, parallel = 1, path = NULL, img.suffix = "ffDTW")

Arguments

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.

A numeric vector of length 1 specifying the window length of the spectrogram, default is 512.

flim

A numeric vector of length 2 for the frequency limit of the spectrogram (in kHz), as in spectro. Default is c(0, 22).

length.out

A character vector of length 1 giving the number of measurements of fundamental frequency desired (the length of the time series).

Character vector of length 1 specifying window name. Default is "hanning". See function ftwindow for more options.

pal

A color palette function to be used to assign colors in the plot, as in spectro. Default is reverse.gray.colors.2.

ovlp

Numeric vector of length 1 specifying % of overlap between two consecutive windows, as in spectro. Default is 70.

inner.mar

Numeric vector with 4 elements, default is c(5,4,4,2). Specifies number of lines in inner plot margins where axis labels fall, with form c(bottom, left, top, right). See par.

outer.mar

Numeric vector with 4 elements, default is c(0,0,0,0). Specifies number of lines in outer plot margins beyond axis labels, with form c(bottom, left, top, right). See par.

picsize

Numeric argument of length 1. Controls relative size of spectrogram. Default is 1.

res

Numeric argument of length 1. Controls image resolution. Default is 100 (faster) although 300 - 400 is recommended for publication/ presentation quality.

cexlab

Numeric vector of length 1 specifying the relative size of axis labels. See spectro.

title

Logical argument to add a title to individual spectrograms. Default is TRUE.

propwidth

Logical argument to scale the width of spectrogram proportionally to duration of the selected call. Default is FALSE.

Numeric vector of length 1. A constant by which to scale spectrogram width. Default is 1.

Logical argument to add grid to spectrogram. Default is FALSE.

Logical argument to add amplitude scale to spectrogram, default is FALSE.

A numeric vector of length 2 for the lower and upper limits of a frequency bandpass filter (in kHz). Default is c(0, 22).

cex

Numeric vector of length 1, specifies relative size of points plotted for frequency measurements and legend font/points, respectively. See spectro.

threshold

amplitude threshold (%) for fundamental frequency detection. Default is 15.

col

Vector of length 1 specifying colors of points plotted to mark fundamental frequency measurements. Default is "red2".

pch

Numeric vector of length 1 specifying plotting characters for the frequency measurements. Default is 16.

mar

Numeric vector of length 1. Specifies the margins adjacent to the selections to set spectrogram limits. Default is 0.05.

lpos

Character vector of length 1 or numeric vector of length 2, specifiying position of legend. If the former, any keyword accepted by xy.coords can be used (see below). If the latter, the first value will be the x coordinate and the second value the y coordinate for the legend's position. Default is "topright".

A character vector of length 1 giving the image type to be used. Currently only "tiff" and "jpeg" are admitted. Default is "jpeg".

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 available 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 sufix (label) to add at the end of the names of image files. Default is NULL.

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 begining 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).

Examples

Run this code

## Not run: 
# # set the temp directory
# setwd(tempdir())
# 
# #load data
# data(list = c("Phae.long1", "Phae.long2","manualoc.df"))
# writeWave(Phae.long2, "Phae.long2.wav") #save sound files 
# writeWave(Phae.long1, "Phae.long1.wav")
# 
# # run function 
# ffDTW(manualoc.df, length.out = 30, flim = c(1, 12), img = T, bp = c(1, 9), wl = 300)
# 
# ## End(Not run)

Run the code above in your browser using DataLab