excess_attenuation {baRulho}R Documentation

Measure excess attenuation


excess_attenuation measures excess attenuation in signals referenced in an extended selection table.


excess_attenuation(X, parallel = 1, pb = TRUE, method = 1, type = "Marten",
bp = NULL, output = "est", hop.size = 1, wl = NULL, ovlp = 70)



object of class 'extended_selection_table' created by the function selection_table from the warbleR package. The data frame must include the following additional columns: 'distance', 'signal.type', 'bottom.freq' and 'top.freq'.


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


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


Numeric vector of length 1 to indicate the 'experimental design' for measuring excess attenuation. Two methods are available:

  • 1: compare all signals with their counterpart that was recorded at the closest distance to source (e.g. compare a signal recorded at 5m, 10m and 15m with its counterpart recorded at 1m). This is the default method.

  • 2: compare all signals with their counterpart recorded at the distance immediately before (e.g. a signal recorded at 10m compared with the same signal recorded at 5m, then signal recorded at 15m compared with same signal recorded at 10m and so on).


Character vector of length 1 to indicate the 'type' of excess attenuation to be used. Two types are available:

  • Marten: as described by Marten et al. 1977:(total_attenuation - spheric_spreading_attenuation) / distance. This is the default method. Attenuation is measured as changes in energy on amplitude RMS (root mean square).

  • Darden: as described by Darden et al 2008: microphone_gain - 20 x log(distance / 10) - 20 x log(envelope_correlation). The function envelope_correlation is used internally. Microphone gain is the combined microphone gain of the reference and re-recorded signals.


Numeric vector of length 2 giving the lower and upper limits of a frequency bandpass filter (in kHz). Default is NULL.


Character vector of length 1 to determine if an extended selection table ('est', default) or a data frame ('data.frame').


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.


A numeric vector of length 1 specifying the window length of the spectrogram, default is NULL. Ignored if bp = NULL. If supplied, 'hop.size' is ignored. Note that lower values will increase time resolution, which is more important for amplitude ratio calculations.


Numeric vector of length 1 specifying the percent overlap between two consecutive windows, as in spectro. Only used when plotting. Default is 70. Only used for bandpass filtering.


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


Extended selection table similar to input data, but also includes a new column (excess.attenuation) with the excess attenuation values.


Marcelo Araya-Salas (marcelo.araya@ucr.ac.cr)


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

spcc; envelope_correlation


# load example data

# using method 1
excess_attenuation(X = playback_est)

# using method 2
excess_attenuation(X = playback_est, method = 2)

[Package baRulho version 1.0.6 Index]