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

 


Importing data from Raven

imp_raven

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 = FALSE:

 #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 <- specan(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 top.freq bottom.freq 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 8.60438 2.22011 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 8.80705 2.16944 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 8.75660 2.21829 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 8.82232 2.31686 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 8.88803 2.28401 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 8.82232 3.00683 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:

catalog(X = rvn.dat.st[1:9, ], flim = c(1, 10), nrow = 3, ncol = 3, same.time.scale = F,
 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(terrain.colors), tags = "sound.files", path = tempdir())