Prelude: converting example data to .wav.

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.

Setting up a survey.

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:

• 20200617_090000
  • Channels file.
  • Run1 folder.
    • Detections file.
    • Settings file.
    • Localizations folder.
    • Spectrograms folder.

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 correct

Preparing to localize detected sounds.

Two 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')

Localizing detected sounds.

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   NA

Estimated 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.7477

In 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.

Conclusion.

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.