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