envelope_correlation {baRulho}  R Documentation 
Measure amplitude envelope correlation
Description
envelope_correlation
measures amplitude envelope correlation of signals referenced in an extended selection table.
Usage
envelope_correlation(X, parallel = 1, pb = TRUE, method = 1, cor.method = "pearson",
ssmooth = NULL, msmooth = NULL, output = "est", hop.size = 11.6, wl = NULL, ovlp = 70)
Arguments
X 
object of class 'extended_selection_table' created by the function 
parallel 
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).
If 
pb 
Logical argument to control if progress bar is shown. Default is 
method 
Numeric vector of length 1 to indicate the 'experimental design' to measure amplitude envelope correlation. Two methods are available:

cor.method 
Character string indicating the correlation coefficient to be applied ("pearson", "spearman", or "kendall", see 
ssmooth 
Numeric vector of length 1 to determine the length of the sliding window used for a sum smooth for amplitude envelope calculation (used internally by 
msmooth 
Numeric vector of length 2 to smooth the amplitude envelope with a mean sliding window for amplitude envelope calculation. The first element is the window length (in number of amplitude values) and the second one the window overlap (used internally by 
output 
Character vector of length 1 to determine if an extended selection table ('est', default) or a data frame ('data.frame'). 
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 numeric vector of length 1 specifying the window length of the spectrogram, default is NULL. If supplied, 'hop.size' is ignored. 
ovlp 
Numeric vector of length 1 specifying the percent overlap between two
consecutive windows, as in 
Details
Amplitude envelope correlation measures the similarity of two signals in the time domain. The function measures the envelope correlation coefficients of signals in which a reference playback has been rerecorded at increasing distances. Values close to 1 means very similar amplitude envelopes (i.e. little degradation has occurred). If envelopes have different lengths (which means signals have different lengths) crosscorrelation is used and the maximum correlation coefficient is returned. Crosscorrelation is achieved by sliding the shortest signal along the largest one and calculating the correlation at each step. The 'signal.type' column must be used to indicate the function to only compare signals belonging to the same category (e.g. songtypes).The function compares each signal type to the corresponding reference signal within the supplied frequency range (e.g. bandpass) of the reference signal ('bottom.freq' and 'top.freq' columns in 'X'). Two methods for calculating envelope correlation are provided (see 'method' argument). Use blur_ratio
to extract envelopes.
Value
Extended selection table similar to input data, but also includes two new columns ('reference' and 'envelope.correlation') with the reference signal and the amplitude envelope correlation coefficients.
Author(s)
Marcelo ArayaSalas (marcelo.araya@ucr.ac.cr)
References
ArayaSalas, M. (2020). baRulho: baRulho: quantifying habitatinduced degradation of (animal) acoustic signals in R. R package version 1.0.2
Apol, C.A., Sturdy, C.B. & Proppe, D.S. (2017). Seasonal variability in habitat structure may have shaped acoustic signals and repertoires in the blackcapped and boreal chickadees. Evol Ecol. 32:5774.
See Also
blur_ratio
, spectral_blur_ratio
Examples
{
# load example data
data("playback_est")
# remove ambient selections
playback_est < playback_est[playback_est$signal.type != "ambient", ]
# method 1
envelope_correlation(X = playback_est)
# method 2
envelope_correlation(X = playback_est, method = 2)
}