excess_attenuation {baRulho} | R Documentation |
Measure excess attenuation
Description
excess_attenuation
measures excess attenuation in signals referenced in an extended selection table.
Usage
excess_attenuation(X, parallel = 1, pb = TRUE, method = 1, type = "Marten",
bp = NULL, output = "est", hop.size = 1, 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). |
pb |
Logical argument to control if progress bar is shown. Default is |
method |
Numeric vector of length 1 to indicate the 'experimental design' for measuring excess attenuation. Two methods are available:
|
type |
Character vector of length 1 to indicate the 'type' of excess attenuation to be used. Two types are available:
|
bp |
Numeric vector of length 2 giving the lower and upper limits of a frequency bandpass filter (in kHz). Default is |
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 1 ms, which is equivalent to ~45 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. Ignored if |
ovlp |
Numeric vector of length 1 specifying the percent overlap between two
consecutive windows, as in |
Details
Excess attenuation is the amplitude loss of a sound in excess due to spherical spreading. With every doubling of distance, sounds attenuate with a 6 dB loss of amplitude (Morton, 1975; Marten & Marler, 1977). Any additional loss of amplitude results in excess attenuation, or energy loss in excess of that expected to occur with distance via spherical spreading, due to atmospheric conditions or habitat (Wiley & Richards, 1978). Low values indicate little signal attenuation. The goal of the function is to measure the excess attenuation on signals in which a reference playback has been re-recorded at increasing distances. The 'signal.type' column must be used to indicate which signals belonging to the same category (e.g. song-types). The function will then compare each signal type to the corresponding reference signal within the frequency range (e.g. bandpass) of the reference signal ('bottom.freq' and 'top.freq' columns in 'X'). Two methods for calculating excess attenuation are provided (see 'method' argument).
Value
Extended selection table similar to input data, but also includes a new column (excess.attenuation) with the excess attenuation values.
Author(s)
Marcelo Araya-Salas (marcelo.araya@ucr.ac.cr)
References
Araya-Salas, M. (2020). baRulho: baRulho: quantifying habitat-induced degradation of (animal) acoustic signals in R. R package version 1.0.2
Darden, SK, Pedersen SB, Larsen ON, & Dabelsteen T. (2008). Sound transmission at ground level in a short-grass prairie habitat and its implications for long-range communication in the swift fox *Vulpes velox*. The Journal of the Acoustical Society of America, 124(2), 758-766.
Marten K, & Marler P. (1977). Sound transmission and its significance for animal vocalization. Behavioral Ecology and Sociobiology, 2(3), 271-290.
Morton ES. (1975). Ecological sources of selection on avian sounds. The American Naturalist, 109(965), 17-34.
See Also
Examples
{
# load example data
data("playback_est")
# using method 1
excess_attenuation(X = playback_est)
# using method 2
excess_attenuation(X = playback_est, method = 2)
}