warbleR (version 1.1.17)

xcorr: Spectrogram cross-correlation

Description

xcorr estimates the similarity of two spectrograms by means of cross-correlation

Usage

xcorr(X, wl =512, bp = 'frange', ovlp=90, dens=0.9, wn='hanning', 
cor.method = "pearson", parallel = 1, path = NULL, pb = TRUE, na.rm = FALSE,
 cor.mat = TRUE)

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

wl

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

bp

A numeric vector of length 2 setting the upper and lower frequency limits (in kHz) in which to compare the signals or "frange" (default) to indicate that values in 'bottom.freq' and 'top.freq' columns will be used as frequency limits. Default is NULL.

ovlp

Numeric vector of length 1 specifying % of overlap between two consecutive windows, as in spectro. Default is 90. High values of ovlp slow down the function but produce more accurate results.

dens

Numeric vector of length 1 specifying the approximate density of points in which to sample amplitude. See makeTemplate. Deafult is 0.9.

wn

A character vector of length 1 specifying the window name as in ftwindow.

cor.method

A character vector of length 1 specifying the correlation method as in cor.

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. Note that progress bar is not accurate as the number of pairwise comparisons decreases on each iteration. The first iteration runs n-1 comparisons while the last one only 1 (n = nrow(X)).

na.rm

Logical. If TRUE all NAs produced when pairwise cross-correlations failed are removed from the results. This means that all selections with at least 1 cross-correlation that failed are excluded.

cor.mat

Logical. If TRUE only the correlation matrix is returned. Default is TRUE.

Value

If corr.mat is TRUE the function returns a matrix with the maximum (peak) correlation for each pairwise comparison. Otherwise it will return a list that includes 1) a data frame with the correlation statistic for each "sliding" step, 2) a matrix with the maximum correlation for each pairwise comparison, and 3) the frequency range.

Details

This function calculates the pairwise similarity of multiple signals by means of spectrogram cross-correlation. This method "slides" one spectrogram over the other calculating a correlation of the amplitude values at each step. The function runs pairwise cross-correlations on several signals and returns a list including the correlation statistic for each "sliding" step as well as the maximum (peak) correlation for each pairwise comparison. To accomplish this the margins of the signals are expanded by half the duration of the signal both before and after the provided time coordinates. The correlation matrix could have NA's if some of the pairwise correlation did not work (common when sound files have been modified by band-pass filters). This function is a modified version of the corMatch and makeTemplate from the awesome R package `monitoR`.

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-234

See Also

xcorr.graph

Examples

# NOT RUN {
{
#load data
data(list = c("Phae.long1", "Phae.long2", "Phae.long3", "Phae.long4","lbh_selec_table"))
writeWave(Phae.long1, file.path(tempdir(), "Phae.long1.wav")) #save sound files
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"))

xcor <- xcorr(X = lbh_selec_table, wl = 300, bp = c(2, 9), ovlp = 90,
dens = 1, wn = 'hanning', cor.method = "pearson", path = tempdir())

}
# }