The warbleR workflow ends with performing automated measurements of meters, analyzing acoustic (dis)similarity of selected signals, and analysis of coordinated singing bouts. For more details about function arguments, input or output, please read the documentation for the function in question (e.g. ?xcorr
). warbleR
is available on both CRAN and GitHub. The GitHub repository will always contain the latest functions and updates. We also published an article on warbleR
documenting the package workflow [1].
Please note that most tools in warbleR
use functions from the seewave, monitoR, tuneR and dtw packages internally. warbleR
has been designed to make the analyses more accessible to average R-users. However, acoustic analysis with warbleR
would not be possible without the tools provided by these additional packages. These packages should be given credit when using warbleR
by including the appropriate citations in publications (e.g. citation("seewave")
).
Nearly all warbleR
functions contain options for parallel processing, which can greatly speed up analyses. See [1] for more details about parallel processing performance. Use parallel processing with caution, particularly if you use a Windows operating system. warbleR
dependencies for parallel processing have not yet been optimized for Windows.
This vignette can be run without an advanced understanding of R, as long as you know how to run code in your R console. However, knowing more about basic R coding would be very helpful to modify the code for your research questions.
library(warbleR)
# set your working directory appropriately
# setwd("/path/to/working directory")
# run this if you have restarted RStudio between vignettes without saving your workspace
# assumes that you are in your /home/username directory
setwd(file.path(getwd(),"warbleR_example"))
# Check your location
getwd()
The function frange.detec
can also help you figure out the frequency range in your signals. Note that if used for a whole recording, frange.detec
will pick up all sounds in the recording.
Although we have been using Phaethornis longirostris vocalizations throughout these vignettes, these signals are harmonically structured. The functions for detecting frequency ranges, frange
and frange.detec
work best on tonal signals, so for this example we will use Great Tinamou ( Tinamus major) songs. We will download a tinamou recording from xeno-canto, make selections and visualize/detect frequency ranges.
tin <- querxc(qword = 'Tinamus', download = FALSE)
# select a single recording
tin <- tin[tin$Recordist == "Marcelo Araya-Salas", ]
# download this recording
querxc(X = tin, download = TRUE)
mp32wav()
Now use Raven to make selections. Make sure to include arguments from imp.raven to ensure selection table is imported with the correct columns for downstream functions
Tin.sels <- run_raven(raven.path = "/home/gsvidaurre/opt/Raven-1.5.0.0035/", sound.files = "Tinamus-major-154191.wav", import = TRUE, all.data = FALSE, name.from.file = TRUE, ext.case = "lower", freq.cols = FALSE)
str(Tin.sels)
# write selections as a physical file you you can read them back in at any time
# good way to save all your work
write.csv(Tin.sels, "Tinamus-major-154191_sels.csv", row.names = FALSE)
# generate individual cuts for freqeuency range measurements below
cut_sels(Tin.sels, mar = 0.05, labels = c("sound.files", "selec"))
Raven selection tables can return low and high frequencies in your selections (e.g. if all.data
or freq.cols
in run_raven
or imp.raven
is TRUE), but the accuracy of these frequency selections depends on how the signals themselves were selected. Below we demonstrate how to visualize and detect the frequency range in your selected signals using the new functions frange.detec
and frange
, which have options for setting bandpass filters to exclude background noise or other non-target acoustic signals.
frange.detec
creates a plot that will print to your graphics device, and also outputs a data frame per recording with the frequency range. This data frame can be used in subsequent analyses if saved as an object. frange.detect
works best with single signals.
# note that changing the threshold argument in combination with the bandpass argument can improve the detection
frange.detec(readWave("Tinamus-major-154191-6.wav"), flim = c(0, 2.5), bp = c(0, 3), threshold = 15)
# here, giving a strict bandpass with very low threshold improves frange detection
# since the curving end of the tinamou signal is lower amplitude than the rest of the signal
frange.detec(readWave("Tinamus-major-154191-6.wav"), flim = c(0, 2.5), bp = c(0, 3), threshold = 1)
The function frange
allows you to simultaneously return the frequency ranges for all signals in a selection table, including the graphical output as frange.detec
. In addition to image files, this function returns the original selection table, as a data frame with the newly calculated low and high frequency measurements.
# use arguments from frange.detec above
fr <- frange(Tin.sels, threshold = 1, res = 100, flim = c(0, 2.5), bp = c(0.5, 2.5))
str(fr)
Spectral entropy can be calculated as time series in selected signals and plotted onto image files. Previously, spectral entropy was only available as a sole measurement across a selection, as an meter measured by specan
.
se <- sp.en.ts(Phae.hisnrt, wl = 300, length.out = 10, threshold = 10, img = TRUE, img.suffix = "sp.en.ts", type = "b", ovlp = 90, sp.en.range = c(-25, 10))
This section on compare.methods
is taken directly from Marcelo Araya-Salas’s bioacoustics GitHub blog with slight modifications.
Bioacoustic research relies on quantifying the structure of acoustic signals and comparing that structure across behavioral/ecological contexts, groups or species. However, measuring signal structure in a way that fully accounts for the variation in the signals could be a tricky task. Some of the differences that are apparent by visual inspection of spectrograms might not be picked up by some analyses. Hence, choosing the most appropriate analytical approach is a critical step.
The warbleR
function compare.methods
attempts to facilitate method selection. This function produces graphs (as image files in the working directory) with spectrograms from 4 signals that allow visual inspection of the performance of acoustic analysis methods at comparing those signals. The signals are randomly picked up from the provided data frame (X
argument), and the function compares 2 warbleR
methods at a time. The methods available are: * cross-correlation by warbleR function xcorr
* dynamic time warping on dominant frequency time series with dfDTW
* dynamic time warping on fundamental frequency time series with ffDTW
* spectral parameters with specan
In the last vignette, we tailored selections of Phaethornis longirostris songs that were originally downloaded from xeno-canto, detected by autodetec
and filtered by signal-to-noise ratio (SNR). Here we will pick up the workflow with these filtered and tailored selections, using the data frame Phae.hisnrt
.
Phae.hisnrt <- read.csv("seltailor_output.csv", header = TRUE)
compare.methods(X = Phae.hisnrt, flim = c(0, 10), bp = c(0, 10),
wl = 300, n = 10, methods = c("XCORR", "dfDTW"))
compare.methods
will produce 10 image files in the working directory (since we specified n = 10
) that look like this:
In this graphic, the acoustic pairwise distance between signals is shown next to the arrows linking them. The font color of a distance value corresponds to the font color of the method that generated it, as shown in the scatterplots (in this case black font represents XCORR distances). Distances are standardized, with 0 being the distance of a signal to itself and 1 the farthest pairwise distance in the pool of signals. Principal Component Analysis (princomp
function) is applied to calculate distances when using spectral parameters (SP). In this case, the first 2 PC’s are used. Classical Multidimensional Scaling (also known as Principal Coordinates Analysis, cmdscale
function) is used for all other methods. The image file name contains the methods being compared and the row number of the selections. This function internally uses a modified version of the spectro
function from the seewave
package to create spectrograms. Note that the spectrograms are all plotted with the same frequency and time scales.
Also note that the graphs contain 2 scatterplots (1 per method) of the acoustic space of all signals in the input data frame X
. The position of the 4 signals in the spectrograms is highlighted in the acoustic space scatterplot. These graphics allow you to directly assess if the distances between signals in the acoustic space accurately represent the spectrographic similarity (e.g. how similar their acoustic structure looks in the spectrograms).
You can run compare.methods
for any combination of the quantative methods for assessing acoustic (dis)similarity mentioned above. Importantly, to include the SP method (spectral parameters measured by the function specan
), you need a large enough dataset, as the PCA that summarizes the spectral parameters needs more units (rows) that variables (columns).
We will move on to explaining each of the acoustic (dis)similarity methods in turn.
trackfreqs
Prior to measuring meters, it’s good practice to visualize the accuracy of some important parameters. The function trackfreqs
allows you to create spectrograms with dominant frequency and fundamental frequency measurements plotted on top of each selected signal.
Use trackfreqs
on all the recordings for which you want to measure meters. Scroll through all the spectrograms to get a feeling for how well the frequency measurements will be performed across your recordings.
Running trackfreqs
can allow you to decide which frequency parameters to use in subsequent analyses, namely specan
and dynamic time warping methods. Also, ff the frequency measurements look acceptable with the bandpass setting used in trackfreqs
, use that same bandpass while running specan
.
# Note that the dominant frequency measurements are almost always more accurate
trackfreqs(Phae.hisnrt, wl = 300, flim = c(2, 10), bp = c(1, 12), it = "jpeg")
# We can change the lower end of bandpass to make the frequency measurements more precise
trackfreqs(Phae.hisnrt, wl = 300, flim = c(1, 10), bp = c(2, 12), col = c("purple", "orange"),
pch = c(17, 3), res = 300, it = "jpeg")
Note that the fundamental frequency measurements are not always very accurate. We will remove fundamental frequency measurements from subsequent analyses.
specan
We can now perform acoustic measurements with the function specan
. This function relies on the temporal coordinates in selection tables to measure 29 meters meters across selections. specan
is a batch process that is faster than calculating measurements manually, e.g. one selection and recording at a time. specan
uses and customizes several functions available in the seewave package
.
Use the bandpass filter to your advantage here, to filter out low or high background noise before performing measurements. Also note that changing the amplitude threshold will change the amplitude at which noises (including non-target signals) are detected for measurements.
params <- specan(Phae.hisnrt, bp = c(2, 10), threshold = 15)
# As always, it's a good idea to write .csv files to your working directory
write.csv(params, "acoustic_parameters.csv", row.names = FALSE)
Make sure to remove parameters derived from fundamental frequency (based on trackfreqs
results).
params <- params[, grep("fun|peakf", colnames(params), invert = TRUE)]
This section on dynamic time warping methods is taken directly from Marcelo Araya-Salas’s bioacoustics GitHub blog with slight modifications.
The dynamic time warping methods in warbleR
all rely on functions from the dtw
package, and are available for both dominant and fundamental frequencies. dfDTW
and ffDTW
calculate the dominant and fundamental frequency contours, respectively, of each signal and compares using dynamic time warping. You can interpolate measurements across the frequency time series using the length.out
argument.
These functions return a matrix of pairwise acoustic dissimilarity (e.g. acoustic “distance”) measurements that can be used in analyses of acoustic similarity, as well as image files with the frequency contours plotted over the spectrograms. If you require only the time series without the dynamic time warping analysis for either the dominant or fundamental frequency, check out the functions dfts
and ffts
.
Note that as the frange
and frange.detec
functions, the dynamic time warping functions tend to work best on more tonal signals.
# Harmonic Phaethornis signals
dm <- dfDTW(Phae.hisnrt, length.out = 30, flim = c(2, 10), bp = c(2, 9), wl = 300, img = TRUE)
# Tonal Tinamou signals
Tin.sels <- read.csv("Tinamus-major-154191_sels.csv", header = TRUE)
dm <- dfDTW(Tin.sels, length.out = 30, flim = c(0, 2.5), bp = c(0.5, 2.5), wl = 512, img = TRUE)
Check out Marcelo’s blog for a great example of how to evaluate whether or not the dynamic time warping (dis)similiarty measurements accurately represents acoustic differences.
Cross-correlation calculates the pairwise similarity of multiple signals by spectrogram cross-correlation. xcorr
calculates a correlation of the amplitude values at each step by sliding one spectrogram over the other. This function is a modified version of the corMatch
and makeTemplate
functions from the package monitoR
. xcorr
runs over multiple signals and returns a list of output, including:
xcorr
requires margins half the duration of the signal on either side of the signal (e.g. before and after the start and end coordinates). Signals that are very close to either the start or end of a recording may throw errors. Additionally, when sound files have been modified by bandpass filters, some pairwise cross-correlations may not work and the correlation matrix may contain NA
values. xcorr
now contains an argument to remove columns of the matrix that contain NA
values, which will reduce the data in the matrix but also allow the matrix to be used in subsequent analyses.
Here our output is a matrix of peak correlation per pairwise comparison, with the recording-selection names as the matrix dimension names.
xc <- xcorr(Phae.hisnrt, wl = 300, na.rm = FALSE, frange = c(2,10))
str(xc)
To visualize the cross-correlation across all pairwise comparisons, we need to feed the function xcorr.graph
a list of xcorr
output (xcorr
must be run with cor.mat = FALSE
). Here we save the graphical output of xcorr.graph
for better ease of visualization.
xc <- xcorr(Phae.hisnrt, wl = 300, na.rm = FALSE, frange = c(2,10), cor.mat = FALSE)
jpeg("xcorr_graph.jpeg", width = 30, height = 30, units = "cm", res = 200)
xcorr.graph(xc, cex.cor = 1, cex.lab = 1, cex.axis.lab = 1)
dev.off()
In this image, red values in the upper triangle indicate high peak correlations and therefore greater similiarty between signals. The faceted line plots in the lower triangle are another way of visualizing similarity between signals. The x-axis is the time difference between signals at each sliding step of the cross-correlation, with 0 representing perfectly centered signals. Plots with peaks at 0 represent signals that are more similar.
specan
measurementsWe can evaluate whether or not the observed variation in song structure is reflected by the meters we just measured. For this we will conduct a Principal Component Analysis on scaled (z-transformed) meters and look at the grouping of songs (data points) in the scatter plot.
# Run the PCA with only numeric variables of params
pca <- prcomp(x = params[, sapply(params, is.numeric)], scale. = TRUE)
# Check loadings
summary(pca)
## Importance of components:
## PC1 PC2 PC3 PC4 PC5 PC6 PC7
## Standard deviation 3.4752 2.4346 2.1121 1.43206 1.11912 0.9768 0.90140
## Proportion of Variance 0.4026 0.1976 0.1487 0.06836 0.04175 0.0318 0.02708
## Cumulative Proportion 0.4026 0.6001 0.7488 0.81720 0.85895 0.8908 0.91783
## PC8 PC9 PC10 PC11 PC12 PC13
## Standard deviation 0.82191 0.73718 0.68124 0.56457 0.41987 0.30650
## Proportion of Variance 0.02252 0.01811 0.01547 0.01062 0.00588 0.00313
## Cumulative Proportion 0.94035 0.95847 0.97394 0.98456 0.99044 0.99357
## PC14 PC15 PC16 PC17 PC18 PC19
## Standard deviation 0.24769 0.21382 0.18432 0.15302 0.12735 0.07694
## Proportion of Variance 0.00205 0.00152 0.00113 0.00078 0.00054 0.00020
## Cumulative Proportion 0.99561 0.99714 0.99827 0.99905 0.99959 0.99979
## PC20 PC21 PC22 PC23
## Standard deviation 0.06257 0.04541 0.01974 2.943e-15
## Proportion of Variance 0.00013 0.00007 0.00001 0.000e+00
## Cumulative Proportion 0.99992 0.99999 1.00000 1.000e+00
# Extract PCA scores
pcascor <- as.data.frame(pca[[5]])
# Plot the 2 first PCs
plot(pcascor[, 1], pcascor[, 2], col = as.numeric(params$sound.files), pch = 20,
cex = 1, xlab = "PC1", ylab = "PC2")
# Add recordings/individuals labels
x <- tapply(pcascor[, 1], params$sound.files, mean)
y <- tapply(pcascor[, 2], params$sound.files, mean)
labs <- gsub(".wav", "", unique(sapply(as.character(params$sound.files), function(x){
strsplit(x, split = "-", fixed = TRUE)[[1]][3]
}, USE.NAMES = FALSE)))
text(x, y, labs, cex = 0.75)
Songs are grouped by sound file. As each sound file represents a single individual, this suggests that songs have individual signatures. Let’s look at the song type level. First, we need to classify the songs by song type. We can check the spectrograms we previously created to do this.
Songs from sound files 154070 and 154072 seem to belong to the same song type. Sound files 154129 and 154161 represent a different song type. Finally, the songs from each of the other 2 sound files have a unique structure, so each one represents a different song type. We can add this information to the plot by using symbols to represent song types.
# Create a song type variable
# First, extract recording ID
songtype <- gsub(".wav", "", sapply(as.character(params$sound.files), function(x){
strsplit(x, split = "-", fixed = TRUE)[[1]][3]
}, USE.NAMES = FALSE))
# Now change IDs for letters representing song types
songtype <- gsub("154070|154072", "A", songtype)
songtype <- gsub("154129|154161", "B", songtype)
songtype <- gsub("154138", "C", songtype)
# Add song type as a variable representing symbol type
plot(pcascor[, 1], pcascor[, 2], col = as.numeric(params$sound.files),
pch = as.numeric(as.factor(songtype)),
cex = 1, xlab = "PC1", ylab = "PC2")
# Add song type labels
x <- tapply(pcascor[, 1], songtype, mean)
y <- tapply(pcascor[, 2], songtype, mean)
text(x, y, unique(songtype), cex = 1)
Songs of the same song type are more similar (they cluster together). This PCA confirms that the visually obvious differences in the song structures are well described by the meters measured in warbleR
. Likewise, it also confirms that we can detect biologically relevant differences from sound files that have undergone mp3 compression and conversion back to wav format (see also [2]). Importantly, if this analysis were for publication we would have to run other filtering steps on the acoustic parameters generated by specan
, including removing any collinear variables.
warbleR
contains functions to visualize and test whether or not singing bouts between individuals can be considered coordinated singing. The function coor.graph
plots signals as polygons to better visualize overlap between these signals.
The function coor.test
uses a Monte Carlo randomization test to determine whether or not the probability of finding overlapping songs in a singing event is less than or more than what you would expect by chance. coor.test
can be run simultaneously for many singing events, if all are contained in a single data frame (see coor.test
documentation for more information).
data(sim.coor.sing)
str(sim.coor.sing)
## 'data.frame': 446 obs. of 4 variables:
## $ sing.event: chr "altern" "altern" "altern" "altern" ...
## $ indiv : chr "indiv.1" "indiv.2" "indiv.1" "indiv.2" ...
## $ start : num 0.437 0.616 1.11 1.425 1.832 ...
## $ end : num 0.562 0.806 1.242 1.626 2.019 ...
The sim.coor.sing
dataset contains three types of singing bouts:
# save plots in a list
g <- coor.graph(sim.coor.sing, it = "jpeg", img = FALSE, res = 300)
# print list of plots to graphics device
g
We can test for overlapping or alternating coordinated singing using the less.than.chance
argument in coor.test
. Here we will test for alternating coordinated singing, since less.than.chance
is set to TRUE
.
cs <- coor.test(sim.coor.sing, iterations = 1000, less.than.chance = TRUE, cutoff = 10)
str(cs)
## 'data.frame': 3 obs. of 4 variables:
## $ sing.event : Factor w/ 3 levels "altern","ovlp",..: 1 2 3
## $ obs.ovlps : int 20 57 39
## $ mean.random.ovlps: num 36.8 38.7 41
## $ p.value : num 0 1 0.352
This concludes the warbleR
vignette series. After running the code in this third vignette, you should now have an idea of how to:
specan
- 29 metersdfDTW
and ffDTW
- dynamic time warpingxcorr
- spectrographic cross-corrrelationIn these vignettes we have done our best to demonstrate how the warbleR
functions can be used in a streamlined workflow for flexible and rigorous bioacoustics analysis. The output of warbleR
functions can be used in other packages for statistical analyses, such as machine learning functions that can be applied to bioacoustics.
In keeping with the nature of writing code, we have attempted to make our code (in particular the code used between functions) as general as possible. In keeping with the open-source nature of R, we welcome all users to provide feedback, updates to functions, comments about bugs or contribute new functions to warbleR's GitHub repository
.