library(locaR)This vignette will introduce users to the localizeMultiple() function, which is a function that can be used to streamline the localization of multiple detections. The localizeMultiple() function is related to, but different from, the localize() function. The following table summarizes the differences:
| localize() | localizeMultiple() |
|---|---|
| Flexible | Rigid |
| Manual data wrangling | Automated data wrangling |
| User writes loops | Loops managed automatically |
Simply put, the localize() function does one thing: localizes a single sound source when provided with the relevant information. The advantage of the localize() function is that it is flexible and can be integrated into any project, with data organized however the user pleases. In contrast, the localizeMultiple() function requires that data be organized a particular way (there is still some flexibility, but it is limited). By organizing data in the right way, localizeMultiple() can localize multiple detections within a survey. It automatically manages some internal processes to speed up the code. Important: the localizeMultiple() function currently only works with sound recordings named according to the Wildlife Acoustics naming convention, that is prefix_date_time.wav or prefix_date$time.wav.
As mentioned, the data organization requirements for the localizeMultiple() function are fairly stringent. Fortunately, locaR has some functions to ease/automate the organization of data. These include the setupSurvey() function, the createSettings() function, and the processSettings() function, among others.
When deciding whether to use the localize() or localizeMultiple() function, a useful consideration is whether you are doing intensive work or extensive work. By intensive, I mean - are you trying to localize every sound source, or nearly every sound source, within short recording sessions? If so, that’s intensive work, and you can use the localizeMultiple() function. If, in contrast, you are localizing only one or a few sounds per recording session, then you’ll have to use the localize() function and wrangle the data yourself. The reason is that it would be too cumbersome to set up an entire “survey”, with all the data wrangling it entails, to localize just one or two sounds. If, in contrast, you are localizing dozens or hundreds of sounds from a single short recording session, it makes sense to set up a “survey” and use the localizeMultiple() function. Of course, the localize() function could also be used in the latter case, but it would likely be more work for the user. Both functions use the same underlying algorithm.
Before we get started, we should convert the example data from .mp3 to .wav. Many of the functions in locaR work exclusively with wav files. Here we will store the wav files in the temporary directory whose contents are deleted at the end of each R session. Feel free to choose another directory if you prefer, since the temporary directory can be hard to find.
#list mp3 files.
f.in <- list.files(system.file('extdata', package = 'locaR'), full.names = T, pattern='mp3$')
#create wav names.
f.out <- file.path(tempdir(), basename(f.in))
#change extension.
substr(f.out, nchar(f.out)-2, nchar(f.out)) <- 'wav'
for(i in 1:length(f.in)) {
y <- tuneR::readMP3(f.in[i])
tuneR::writeWave(y, filename = f.out[i])
}Now we can proceed.
The first step to using localizeMultiple() is to set up a “survey”, which just means organizing the data for a particular recording session in a standardized way. This was already done for the example data in the “Detecting Sound Sources” vignette. To briefly summarize what it entails, each recording session must be organized according to the following file/folder structure:
This can all be set up easily using the setupSurvey() function. Here we will set up the survey in the temporary directory, whose contents are deleted at the end of each R session. Feel free to choose another directory if you prefer, since the temporary directory can be hard to find.
survey <- setupSurvey(folder = tempdir(), projectName = 'Ex', run = 1,
coordinatesFile = system.file('extdata', 'Vignette_Coordinates.csv', package = 'locaR'),
siteWavsFolder = tempdir(),
date = '20200617', time = '090000', surveyLength = 7)
#> Run == 1 and survey folder (i.e. /folder/date_time) exists.
#> New files not written. Folder structure appears to be correctTwo more steps are needed prior to the localization step.
First, we must add the example detections to the mix. The above code has set up a survey in the specified location (here, the folder provided by tempdir()), but doing so, it created a detections file that is empty. Let’s fill it with the example detection data provided with the package. For details on how to fill out a detections file from scratch, see vignette 2: “Detecting sound sources”.
#read example detections.
dets <- read.csv(system.file('extdata', 'Vignette_Detections_20200617_090000.csv', package = 'locaR'))
#over-write empty detections file.
write.csv(dets, file.path(tempdir(), '20200617_090000', 'Run1', 'Ex_20200617_090000_Run1_Detections.csv'), row.names = F)The final step is to process the settings file. This step organizes relevant information into a list that can be passed to the localizeMultiple() function for localization.
Prior to this step, ensure that the mp3 files have been converted to wav. See the “Detecting sound sources” vignette for code to do that.
st <- processSettings(settings = survey, getFilepaths = TRUE, types = 'wav')The primary advantage of using the localizeMultiple() function is that, once everything has been set up, the localization of many sounds within a recording session can be carried out with a single line of code:
locs <- localizeMultiple(st = st, indices = 'all')The above code feeds the list of settings information (the st object) into the localization algorithm. Typing indices = 'all' tells the function to localize all the detected sounds. Numbers could be used instead to localize only one or a few detections; I sometimes set indices = 1 to test things out before running them all.
If the above code ran correctly, then the locs object should look like this:
#> Station1 Station2 Station3 Station4 Station5 Station6 From To F_Low F_High
#> 1 Ex-8 Ex-5 Ex-6 Ex-9 Ex-4 NA 0.8 1.1 2000 6500
#> 2 Ex-8 Ex-5 Ex-6 Ex-9 Ex-4 NA 1.9 2.2 2000 6500
#> 3 Ex-8 Ex-5 Ex-6 Ex-9 Ex-4 NA 2.8 3.1 2000 6500
#> 4 Ex-8 Ex-5 Ex-6 Ex-9 Ex-4 NA 4.2 4.5 2000 6500
#> 5 Ex-8 Ex-5 Ex-6 Ex-9 Ex-4 NA 5.0 5.3 2000 6500
#> 6 Ex-8 Ex-5 Ex-6 Ex-9 Ex-4 NA 6.1 6.4 2000 6500
#> 7 Ex-5 Ex-2 Ex-3 Ex-6 <NA> NA 4.0 5.9 4000 8000
#> Species Individual Comments Easting Northing Elevation Power Keep
#> 1 REVI 1 NA 371336.5 5934570 745.2959 18.306839 NA
#> 2 REVI 1 NA 371336.5 5934570 745.2959 18.053934 NA
#> 3 REVI 1 NA 371336.5 5934570 744.2959 15.702368 NA
#> 4 REVI 1 NA 371335.5 5934570 745.2959 17.048126 NA
#> 5 REVI 1 NA 371335.5 5934570 746.2959 16.438755 NA
#> 6 REVI 1 NA 371336.5 5934572 739.2959 12.678592 NA
#> 7 CCSP 1 NA 371344.9 5934606 737.7477 4.611462 NAEstimated locations (x, y and z coordinates) can be found in the columns labeled Easting, Northing, and Elevation.
#> Easting Northing Elevation
#> 1 371336.5 5934570 745.2959
#> 2 371336.5 5934570 745.2959
#> 3 371336.5 5934570 744.2959
#> 4 371335.5 5934570 745.2959
#> 5 371335.5 5934570 746.2959
#> 6 371336.5 5934572 739.2959
#> 7 371344.9 5934606 737.7477In addition, the jpeg images will have been created in the folder ‘./20200617_090000/Run1/Localizations/’, in this case in the R Session’s temporary directory. Interpreting these was covered in the “Introduction to localize” vignette.
This vignette introduced the localizeMultiple() function, and described some of the advantages of this function compared with the localize() function. More than anything, the advantages can be seen in the brevity of this vignette, which required only five lines of code; the “Introduction to localize()” vignette, by contrast, contained dozens of lines of code, and much more technical knowledge.