spcc {baRulho}

Measure spectrographic cross-correlation as a measure of sound distortion

Description

spcc measures spectrographic cross-correlation as a measure of sound distortion in sounds referenced in an extended selection table.

Usage

spcc(
  X,
  cores = getOption("mc.cores", 1),
  pb = getOption("pb", TRUE),
  cor.method = c("pearson", "spearman", "kendall"),
  hop.size = getOption("hop.size", 11.6),
  wl = getOption("wl", NULL),
  ovlp = getOption("ovlp", 90),
  wn = "hanning",
  path = getOption("sound.files.path", ".")
)

Arguments

X

The output of set_reference_sounds which is an object of class 'data.frame', 'selection_table' or 'extended_selection_table' (the last 2 classes are created by the function selection_table from the warbleR package) with the reference to the test sounds . Must contain the following columns: 1) "sound.files": name of the .wav files, 2) "selec": unique selection identifier (within a sound file), 3) "start": start time and 4) "end": end time of selections, 5) "bottom.freq": low frequency for bandpass, 6) "top.freq": high frequency for bandpass, 7) "sound.id": ID of sounds used to identify counterparts across distances and 8) "reference": identity of sounds to be used as reference for each test sound (row). See set_reference_sounds for more details on the structure of 'X'.

cores

Numeric vector of length 1. Controls whether parallel computing is applied by specifying the number of cores to be used. Default is 1 (i.e. no parallel computing).

pb

Logical argument to control if progress bar is shown. Default is TRUE.

cor.method

Character string indicating the correlation coefficient to be applied ("pearson", "spearman", or "kendall", see cor).

hop.size

A numeric vector of length 1 specifying the time window duration (in ms). Default is 11.6 ms, which is equivalent to 512 wl for a 44.1 kHz sampling rate. Ignored if 'wl' is supplied.

wl

a vector with a single even integer number specifying the window length of the spectrogram, default is NULL. If supplied, 'hop.size' is ignored. Odd integers will be rounded up to the nearest even number.

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.

wn

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

path

Character string containing the directory path where the sound files are found. Only needed when 'X' is not an extended selection table. If not supplied the current working directory is used.

Details

Spectrographic cross-correlation measures frequency distortion of sounds as a similarity metric. Values close to 1 means very similar spectrograms (i.e. little sound distortion has occurred). Cross-correlation is measured of sounds in which a reference playback has been re-recorded at increasing distances. The 'sound.id' column must be used to indicate the function to only compare sounds belonging to the same category (e.g. song-types). The function compares each sound to the corresponding reference sound within the supplied frequency range (e.g. bandpass) of the reference sound ('bottom.freq' and 'top.freq' columns in 'X'). Two methods for computing cross-correlation are provided (see 'method' argument). The function is a wrapper on warbleR's cross_correlation function.

Value

Object 'X' with an additional column, 'cross.correlation', containing the computed spectrogram cross-correlation coefficients.

Author(s)

Marcelo Araya-Salas ([e-mail])

References

Araya-Salas M., E. Grabarczyk, M. Quiroz-Oliva, A. Garcia-Rodriguez, A. Rico-Guevara. (2023), baRulho: an R package to quantify degradation in animal acoustic signals .bioRxiv 2023.11.22.568305.

Clark, C.W., Marler, P. & Beeman K. (1987). Quantitative analysis of animal vocal phonology: an application to Swamp Sparrow song. Ethology. 76:101-115.

See Also

blur_ratio, manual_realign, cross_correlation

Other quantify degradation: blur_ratio(), detection_distance(), envelope_correlation(), plot_blur_ratio(), plot_degradation(), set_reference_sounds(), signal_to_noise_ratio(), spectrum_blur_ratio(), spectrum_correlation(), tail_to_signal_ratio()

Examples

{
  # load example data
  data("test_sounds_est")

  # add reference to X
  X <- set_reference_sounds(X = test_sounds_est)

  # get spcc
  spcc(X = X)
}