View source: R/plot_degradation.R
plot_degradation | R Documentation |
plot_degradation
creates multipanel plots (as image files) with reference and test sounds by distance and transect.
plot_degradation(
X,
nrow = 4,
env.smooth = getOption("env.smooth", 200),
hop.size = getOption("hop.size", 11.6),
wl = getOption("wl", NULL),
ovlp = getOption("ovlp", 70),
path = getOption("sound.files.path", "."),
dest.path = getOption("dest.path", "."),
cores = getOption("mc.cores", 1),
pb = getOption("pb", TRUE),
collevels = seq(-120, 0, 5),
palette = viridis::viridis,
flim = c("-1", "+1"),
envelope = TRUE,
spectrum = TRUE,
heights = c(4, 1),
widths = c(5, 1),
margins = c(2, 1),
row.height = 2,
col.width = 2,
cols = viridis::mako(4, alpha = 0.3),
res = 120,
...
)
X |
The output of |
nrow |
Numeric vector of length 1 with the number of rows per image file. Default is 4. This would be dynamically adjusted if more rows than needed are set. |
env.smooth |
Numeric vector of length 1 determining the length of the sliding window (in amplitude samples) used for a sum smooth for amplitude envelope and power spectrum calculations (used internally by |
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. Can be set globally for the current R session via the "hop.size" option (see |
wl |
a vector with a single even integer number specifying the window length of the spectrogram, default is |
ovlp |
Numeric vector of length 1 specifying the percentage of overlap between two
consecutive windows, as in |
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. Can be set globally for the current R session via the "sound.files.path" option (see |
dest.path |
Character string containing the directory path where the image files will be saved. If not supplied the current working directory will be used instead. Can be set globally for the current R session via the "dest.path" option (see |
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). Can be set globally for the current R session via the "mc.cores" option (see |
pb |
Logical argument to control if progress bar is shown. Default is |
collevels |
Numeric vector indicating a set of levels which are used to partition the amplitude range of the spectrogram (in dB) as in |
palette |
A color palette function to be used to assign colors in the
plot, as in |
flim |
A numeric vector of length 2 indicating the highest and lowest frequency limits (kHz) of the spectrogram, as in |
envelope |
Logical to control if envelopes are plotted. Default is |
spectrum |
Logical to control if power spectra are plotted. Default is |
heights |
Numeric vector of length 2 to control the relative heights of spectrogram (first number) and amplitude envelope (second number) when |
widths |
Numeric vector of length 2 to control the relative widths of spectrogram (first number) and power spectrum (second number) when |
margins |
Numeric vector of length 2 to control the relative time of the test sound (first number) and adjacent margins (i.e. adjacent background noise, second number) to be included in the spectrogram |
row.height |
Numeric vector of length 1 controlling the height (in inches) of sound panels in the output image file. Default is 2. |
col.width |
Numeric vector of length 1 controlling the width (in inches) of sound panels in the output image file. Default is 2. |
cols |
Character vector of length 4 containing the colors to be used for the background of column and row title panels (element 1), the color of amplitude envelopes (element 2), the color of power spectra (element 3), and the background color of envelopes and spectra (element 4). |
res |
Numeric argument of length 1. Controls image resolution. Default is 120 (faster) although 300 - 400 is recommended for publication/presentation quality. |
... |
Additional arguments to be passed to the internal spectrogram
creating function for customizing graphical output. The function is a modified
version of |
The function aims to simplify the visual inspection of sound degradation by producing multipanel figures (saved in 'dest.path') containing visualizations of each test sound and its reference. Sounds are sorted by distance (columns) and transect (if more than 1). Visualizations include spectrograms, amplitude envelopes and power spectra (the last 2 are optional). Each row includes all the copies of a sound id for a given transect (the row label includes the sound id in the first line and transect in the second line), also including its reference if it comes from another transect. Ambient noise annotations (sound.id 'ambient') are excluded. Amplitude envelopes and power spectra are computed using the functions envelope
(warbleR package) and spec
(seewave package) respectively. This two visualizations show the power distribution in time and frequency between the minimum and maximum power values for each sound. Therefore scales are not necessarily comparable across panels.
One ore more image files with a multipanel figure of spectrograms of test sound by distance, sound id and transect. It also returns the file path of the images invisibly.
Marcelo Araya-Salas (marcelo.araya@ucr.ac.cr)
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.
blur_ratio
, plot_aligned_sounds
, plot_degradation
Other quantify degradation:
blur_ratio()
,
detection_distance()
,
envelope_correlation()
,
plot_blur_ratio()
,
set_reference_sounds()
,
signal_to_noise_ratio()
,
spcc()
,
spectrum_blur_ratio()
,
spectrum_correlation()
,
tail_to_signal_ratio()
# load example data
data("test_sounds_est")
# order so spectrograms from same sound id as close in the graph
test_sounds_est <- test_sounds_est[order(test_sounds_est$sound.id), ]
# set directory to save image files
options(dest.path = tempdir())
# method 1
Y <- set_reference_sounds(X = test_sounds_est)
# plot degradation spectrograms
plot_degradation(
X = Y, nrow = 3, ovlp = 95
)
# using other color palettes
plot_degradation(
X = Y, nrow = 3, ovlp = 95,
cols = viridis::magma(4, alpha = 0.3),
palette = viridis::magma
)
# missing some data, 2 rows
plot_degradation(
X = Y[-3, ], nrow = 2, ovlp = 95,
cols = viridis::mako(4, alpha = 0.4), palette = viridis::mako, wl = 200
)
# changing marging and high overlap
plot_degradation(X = Y, margins = c(5, 1), nrow = 6, ovlp = 95)
# more rows than needed (will adjust it automatically)
plot_degradation(X = Y, nrow = 10, ovlp = 90)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.