The Rraven package is designed to facilitate the exchange of data between R and Raven sound analysis software (Cornell Lab of Ornithology). Raven provides very powerful tools for the analysis of (animal) sounds. R can simplify the automatization of complex routines of analyses. Furthermore, R packages as warbleR, seewave and monitoR (among others) provide additional methods of analysis, working as a perfect complement for those found in Raven. Hence, bridging these applications can largely expand the bioacoustician’s toolkit.
Currently, most analyses in Raven cannot be run in the background from a command terminal. Thus, most Rraven functions are design to simplify the exchange of data between the two programs, and in some cases, export files to Raven for further analysis. This vignette provides detailed examples for each function in Rraven, including both the R code as well as the additional steps in Raven required to fully accomplished the analyses. Raven Pro must be installed to be able to run some of the code. Note that the animations explaining these additional Raven steps are shown in more detail in the github version of this vignette, which can be downloaded as follows (saves the file “Rraven.github.html” in your current working directory):
download.file(
url = "https://raw.githubusercontent.com/maRce10/Rraven/master/gifs/Rraven.hitgub.html",
destfile = "Rraven.github.html")
The downloaded file can be opened by any internet browser.
Before getting into the functions, the packages must be installed and loaded. I recommend using the latest developmental version, which is found in github. To do so, you need the R package devtools (which of course should be installed!). Some warbleR functions and example data sets will be used, so warbleR should be installed as well:
devtools::install_github("maRce10/warbleR")
devtools::install_github("maRce10/Rraven")
#from CRAN would be
#install.packages("warbleR")
#load packages
library(warbleR)
library(Rraven)
Let’s also use a temporary folder as the working directory in which to save all sound files and data files:
setwd(tempdir())
#load example data
data(list = c("Phae.long1", "Phae.long2", "Phae.long3", "Phae.long4", "selec.table", "selection_files"))
#save sound files in temporary directory
writeWave(Phae.long1, "Phae.long1.wav", extensible = FALSE)
writeWave(Phae.long2, "Phae.long2.wav", extensible = FALSE)
writeWave(Phae.long3, "Phae.long3.wav", extensible = FALSE)
writeWave(Phae.long4, "Phae.long4.wav", extensible = FALSE)
#save Raven selection tables in the temporary directory
out <- lapply(1:4, function(x)
writeLines(selection_files[[x]], con = names(selection_files)[x]))
#this is the temporary directory location (of course different each time is run)
getwd()
This function imports Raven selection tables. Multiple files can be imported at once. Raven selection tables including data from multiple recordings can also be imported. It returns a single data frame with the information contained in the selection files. We already have 2 Raven selection tables in the working directory:
list.files(path = tempdir(), pattern = "\\.txt$")[1] "LBH 1 selection table example.txt" "LBH 2 selection table example.txt" "LBH 3 selection table example.txt" "LBH 4 selection table example.txt"
This code shows how to import all the data contained in those files into R:
#providing the name of the column with the sound file names
rvn.dat <- imp_raven(all.data = TRUE, path = tempdir())
head(rvn.dat)| Selection | View | Channel | Begin Time (s) | End Time (s) | Low Freq (Hz) | High Freq (Hz) | Begin File | channel | Begin Path | File Offset (s) | File Offset | selec.file |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 1 | Spectrogram 1 | 1 | 1.1693549 | 1.3423884 | 2220.105 | 8604.378 | Phae.long1.wav | 1 | /tmp/RtmpWpOeaR/Phae.long1.wav | 1.1693549 | NA | LBH 1 selection table example.txt |
| 2 | Spectrogram 1 | 1 | 2.1584085 | 2.3214565 | 2169.437 | 8807.053 | Phae.long1.wav | 1 | /tmp/RtmpWpOeaR/Phae.long1.wav | 2.1584085 | NA | LBH 1 selection table example.txt |
| 3 | Spectrogram 1 | 1 | 0.3433366 | 0.5182553 | 2218.294 | 8756.604 | Phae.long1.wav | 1 | /tmp/RtmpWpOeaR/Phae.long1.wav | 0.3433366 | NA | LBH 1 selection table example.txt |
| 1 | Spectrogram 1 | 1 | 0.1595983 | 0.2921692 | 2316.862 | 8822.316 | Phae.long2.wav | 1 | /tmp/RtmpWpOeaR/Phae.long2.wav | 0.1595983 | NA | LBH 2 selection table example.txt |
| 2 | Spectrogram 1 | 1 | 1.4570585 | 1.5832087 | 2284.006 | 8888.027 | Phae.long2.wav | 1 | /tmp/RtmpWpOeaR/Phae.long2.wav | 1.4570585 | NA | LBH 2 selection table example.txt |
| 1 | Spectrogram 1 | 1 | 0.6265520 | 0.7577715 | 3006.834 | 8822.316 | Phae.long3.wav | 1 | /tmp/RtmpWpOeaR/Phae.long3.wav | NA | 0.626552 | LBH 3 selection table example.txt |
Note that the ‘waveform’ view data has been removed. It can also be imported as follows (but note that the example selection tables have no waveform data):
rvn.dat <- imp_raven(all.data = TRUE, waveform = TRUE,
path = tempdir())
Raven selections can also be imported in a ‘selection.table’ format so it can be directly input into warbleR functions. To do this you need to set warbler.format = TRUE:
#providing the name of the column with the sound file names
rvn.dat <- imp_raven(sound.file.col = "End.File",
warbler.format = TRUE, path = tempdir())
head(rvn.dat)| selec | Channel | start | end | bottom.freq | top.freq | sound.files | channel | selec.file |
|---|---|---|---|---|---|---|---|---|
| 1 | 1 | 1.169355 | 1.342388 | 2.22011 | 8.60438 | Phae.long1.wav | 1 | LBH 1 selection table example.txt |
| 2 | 1 | 2.158408 | 2.321457 | 2.16944 | 8.80705 | Phae.long1.wav | 1 | LBH 1 selection table example.txt |
| 3 | 1 | 0.343337 | 0.518255 | 2.21829 | 8.75660 | Phae.long1.wav | 1 | LBH 1 selection table example.txt |
| 1 | 1 | 0.159598 | 0.292169 | 2.31686 | 8.82232 | Phae.long2.wav | 1 | LBH 2 selection table example.txt |
| 2 | 1 | 1.457058 | 1.583209 | 2.28401 | 8.88803 | Phae.long2.wav | 1 | LBH 2 selection table example.txt |
| 1 | 1 | 0.626552 | 0.757771 | 3.00683 | 8.82232 | Phae.long3.wav | 1 | LBH 3 selection table example.txt |
The data frame contains the following columns: sound.files, channel, selec, start, end, and selec.file. You can also import the frequency range parameters in the ‘selection.table’ by setting ‘freq.cols’ tp TRUE. The data frame returned by “imp_raven” (when in the ‘warbleR’ format) can be input into several warbleR functions for further analysis. For instance, the following code runs additional parameter measurements on the imported selections:
# convert to class selection.table
rvn.dat.st <- selection_table(rvn.dat, path = tempdir())
sp <- spectro_analysis(X = rvn.dat, bp = "frange", wl = 150,
pb = FALSE, ovlp = 90, path = tempdir())
head(sp)checking selections (step 1 of 2):
all selections are OK | sound.files | selec | duration | meanfreq | sd | freq.median | freq.Q25 | freq.Q75 | freq.IQR | time.median | time.Q25 | time.Q75 | time.IQR | skew | kurt | sp.ent | time.ent | entropy | sfm | meandom | mindom | maxdom | dfrange | modindx | startdom | enddom | dfslope | meanpeakf |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Phae.long1.wav | 1 | 0.173033 | 5.98235 | 1.39969 | 6.33172 | 5.29658 | 6.86952 | 1.57294 | 0.076455 | 0.046568 | 0.117463 | 0.070895 | 1.99804 | 7.02156 | 0.943429 | 0.886904 | 0.836731 | 0.651002 | 6.49105 | 3.825 | 8.325 | 4.50 | 7.20000 | 6.975 | 7.575 | 3.46754 | 7.125 |
| Phae.long1.wav | 2 | 0.163048 | 5.99730 | 1.42293 | 6.21213 | 5.32875 | 6.88079 | 1.55205 | 0.076655 | 0.043903 | 0.115680 | 0.071777 | 1.91836 | 7.33432 | 0.946822 | 0.888565 | 0.841313 | 0.667865 | 6.71394 | 3.975 | 8.475 | 4.50 | 4.90000 | 6.825 | 7.275 | 2.75992 | 6.975 |
| Phae.long1.wav | 3 | 0.174919 | 6.02060 | 1.51554 | 6.42844 | 5.15281 | 6.98331 | 1.83050 | 0.090243 | 0.053452 | 0.127729 | 0.074277 | 2.49536 | 11.13912 | 0.945082 | 0.886654 | 0.837961 | 0.671589 | 6.53271 | 2.325 | 8.625 | 6.30 | 10.30952 | 2.925 | 7.275 | 24.86869 | 7.125 |
| Phae.long2.wav | 1 | 0.132571 | 6.39830 | 1.34041 | 6.59597 | 5.60732 | 7.38085 | 1.77353 | 0.076867 | 0.054300 | 0.103665 | 0.049364 | 1.56852 | 6.01639 | 0.942466 | 0.895480 | 0.843959 | 0.608618 | 6.48287 | 4.875 | 8.025 | 3.15 | 11.47619 | 4.875 | 6.225 | 10.18323 | 7.425 |
| Phae.long2.wav | 2 | 0.126150 | 6.31184 | 1.37004 | 6.60202 | 5.60983 | 7.21321 | 1.60338 | 0.076103 | 0.052849 | 0.097947 | 0.045098 | 2.46900 | 10.88435 | 0.935771 | 0.897677 | 0.840020 | 0.615104 | 6.17614 | 3.075 | 7.725 | 4.65 | 9.58065 | 5.625 | 5.775 | 1.18906 | 6.675 |
| Phae.long3.wav | 1 | 0.131220 | 6.61240 | 1.09312 | 6.67013 | 6.06721 | 7.34937 | 1.28215 | 0.063505 | 0.043043 | 0.089613 | 0.046571 | 1.77369 | 6.62602 | 0.930244 | 0.895888 | 0.833394 | 0.570215 | 6.75629 | 4.875 | 8.175 | 3.30 | 11.04546 | 5.475 | 8.025 | 19.43308 | 6.675 |
And this code creates song catalogs:
# create a color palette
trc <- function(n) terrain.colors(n = n, alpha = 0.3)
# plot catalog
catalog(X = rvn.dat.st[1:9, ], flim = c(1, 10), nrow = 3, ncol = 3,
same.time.scale = TRUE, spec.mar = 1, box = FALSE,
ovlp = 90, parallel = 1, mar = 0.01, wl = 200,
pal = reverse.heat.colors, width = 20,
labels = c("sound.files", "selec"), legend = 1,
tag.pal = list(trc), group.tag = "sound.files", path = tempdir())