blur_ratio {baRulho} | R Documentation |
Measure blur ratio in the time domain
Description
blur_ratio
measures blur ratio in signals referenced in an extended selection table.
Usage
blur_ratio(X, parallel = 1, pb = TRUE, method = 1, ssmooth = 200,
msmooth = NULL, output = "est", img = FALSE, res = 150, hop.size = 11.6, wl = NULL,
ovlp = 70, pal = reverse.gray.colors.2, collevels = seq(-60, 0, 5), dest.path = NULL)
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 envelope correlation. Two methods are available:
|
ssmooth |
Numeric vector of length 1 determining the length of the sliding window (in amplitude samples) 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), a data frame ('data.frame') or a list ("list") containing the extended selection table (first object in the list) and all (smoothed) wave envelopes (second object in the list) is returned. The envelope data can be used for plotting. |
img |
Logical argument to control if image files in 'jpeg' format containing the images being compared and the corresponding envelopes are produced. Default is no images ( |
res |
Numeric argument of length 1. Controls image resolution. Default is 150 (faster) although 300 - 400 is recommended for publication/presentation quality. |
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 |
pal |
A color palette function to be used to assign colors in the
plot, as in |
collevels |
Numeric vector indicating a set of levels which are used to partition the amplitude range of the spectrogram (in dB) as in |
dest.path |
Character string containing the directory path where the image files will be saved. If NULL (default) then the folder containing the sound files will be used instead. |
Details
Blur ratio measures the degradation of sound as a function of the change in signal energy in the time domain as described by Dabelsteen et al (1993). Low values indicate low degradation of signals. The function measures the blur ratio on signals in which a reference playback has been re-recorded at different distances. Blur ratio is measured as the mismatch between amplitude envelopes (expressed as probability density functions) of the reference signal and the re-recorded signal. 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'). The 'signal.type' column must be used to tell the function to only compare signals belonging to the same category (e.g. song-types). Two methods for setting the experimental design are provided. All wave objects in the extended selection table must have the same sampling rate so the length of envelopes is comparable.
Value
Data frame similar to input data, but also includes two new columns ('reference' and 'blur.ratio')
with the reference signal and blur ratio values. If img = TRUE
it also returns 1 image file (in 'jpeg' format) for each comparison showing spectrograms of both signals and the overlaid amplitude envelopes (as probability mass functions (PMF)). Spectrograms are shown within the frequency range of the reference signal and also show vertical lines with the start and end of signals to allow users to visually check alignment. If output = 'list'
the output would be a list including the data frame just described and a data frame with envelopes (amplitude values) for all signals.
Author(s)
Marcelo Araya-Salas (marcelo.araya@ucr.ac.cr)
References
Dabelsteen, T., Larsen, O. N., & Pedersen, S. B. (1993). Habitat-induced degradation of sound signals: Quantifying the effects of communication sounds and bird location on blur ratio, excess attenuation, and signal-to-noise ratio in blackbird song. The Journal of the Acoustical Society of America, 93(4), 2206.
Araya-Salas, M. (2020). baRulho: baRulho: quantifying habitat-induced degradation of (animal) acoustic signals in R. R package version 1.0.2
See Also
envelope_correlation
, spectral_blur_ratio
Examples
{
# load example data
data("playback_est")
# remove ambient selections
playback_est <- playback_est[playback_est$signal.type != "ambient", ]
# using method 1
blur_ratio(X = playback_est)
# using method 2
blur_ratio(X = playback_est, method = 2)
}