Create InitData.

Description

Internal function which creates the InitData list.

Usage

MSRP_Init(NodeInfo, SearchMap, Para, LevelFlag)

Arguments

Value

List.

Author(s)

Tim Huang.

Internal function for localization.

Description

This function uses the InitData and other info to calculate the likelihood of sound sources coming from each location. Note: the LevelFlag argument is currently redundant because there is only one option. Similarly, the MSRP_HT_Level2 function could be rolled into the MSRP_RIJ_HT function in the future, but for now is kept separate.

Usage

MSRP_RIJ_HT(NodeInfo, SearchMap, Data, Para, LevelFlag, InitData)

MSRP_HT_Level2(NodeInfo, SearchMap, Data, Para, InitData)

Arguments

Value

List.

Author(s)

Tim Huang.

Generalized cross-correlation.

Description

Internal function that calculates the generalized cross correlation.

Usage

Rij_GCC(data1, data2, Para)

Arguments

Value

Numeric vector.

Author(s)

Tim Huang

Check the validity of a settings file or data.frame.

Description

Several checks are run:

1. settings is either a valid file or a data.frame.

2. That the adjustments file is either an existing file or ""

3. That the channels file is either an existing file or NULL.

4. That the coordinates file exists.

5. That the detections file exists.

6. That the siteWavsFolder exists.

7. That buffer, margin, resolution, date, time, zMin, zMax and surveyLength can all be recognized as numbers.

8. That tempC or soundSpeed have been defined.

Usage

checkSettings(settings)

Arguments

Value

Logical, indicating whether all checks were passed or not.

Create settings file (csv) or data frame by defining the localization settings.

Description

createSettings takes a series of arguments and creates a data frame (or csv) with standard structure that can be read by other functions in the locaR package.

Usage

createSettings(
  projectName,
  run = 1,
  detectionsFile,
  coordinatesFile,
  siteWavsFolder,
  adjustmentsFile,
  channelsFile,
  date,
  time,
  tempC = 15,
  soundSpeed,
  surveyLength,
  margin = 10,
  zMin = -1,
  zMax = 10,
  resolution = 1,
  buffer = 0.2,
  write.csv = FALSE
)

Arguments

Value

A data frame with columns Setting and Value specifying the value of each setting needed for localization.

Create a list of Wave objects.

Description

This function reads in portions of a set of synchronized .wav files. It is intended to be used to load sounds of interest for localization.

Usage

createWavList(
  paths,
  names,
  from,
  to,
  buffer,
  adjustments,
  channels,
  index = "unknown"
)

Arguments

Value

Named list of Wave objects.

Examples

    #list example mp3 files.
    wavs <- list.files(system.file('extdata', package = 'locaR'),
                       pattern = 'mp3$', full.names = TRUE)
    #get names of mp3 locations.
    nms <- substr(basename(wavs), 1, 4)
    #create wave list.
    wl <- createWavList(paths = wavs, names = nms, from = 1, to = 2, buffer = 0.1)

Get filepath information for a date and time.

Description

getFilepaths reads information from a settings file (csv) or a settings list and returns the file paths and other information as a dataframe. It undertakes a recursive search within the site folder for files matching the date and time.

Usage

getFilepaths(settings, types = "wav")

Arguments

Value

A data frame with station names, coordinates, filepaths, and any recording start-time adjustments.

Examples

    #Read example data
    settings <- read.csv(system.file('extdata',
                   'Ex_20200617_090000_Settings.csv', package = 'locaR'),
                   stringsAsFactors = FALSE)

    #Over-write default values for SiteWavsFolder, CoordinatesFile, and ChannelsFile
    settings$Value[settings$Setting == 'SiteWavsFolder'] <-
                  system.file('extdata', package = 'locaR')
    settings$Value[settings$Setting == 'CoordinatesFile'] <-
                   system.file('extdata', 'Vignette_Coordinates.csv',
                               package = 'locaR')
    settings$Value[settings$Setting == 'ChannelsFile'] <-
                   system.file('extdata', 'Vignette_Channels.csv',
                               package = 'locaR')

    #Run processSettings() function
    st <- processSettings(settings = settings, getFilepaths = FALSE)

    #Get filepaths.
    fp <- getFilepaths(settings = st, types = 'mp3')

Specify the spatial layout of microphones.

Description

layoutMatrix creates a matrix of station names, which correspond to the layout of stations in space.This is passed to the omniSpectro function for the purposes of generating spectrograms that align with the spatial orientation of stations. The four user-specified arguments indicate where the first station occurs (e.g. topleft means the first station is in the northwest; the "first" station means the one with the name that would appear first when sorted alphabetically). byrow means the stations increase along rows (either left to right or right to left) and nrow and ncol indicate how many rows and columns of microphones there are (assuming the array has a rectangular shape). Note that this layout function is provided for convenience, but users can easily specify their own custom layouts manually.

Usage

layoutMatrix(
  st,
  stationNames = NULL,
  start = c("topleft", "topright", "bottomleft", "bottomright"),
  byrow = TRUE,
  nrow,
  ncol
)

Arguments

Value

Matrix, containing the station names within the array. If done correctly, the matrix rows and columns should align with the spatial layout of the stations in the field.

Examples

    #Vector of station names, Ex-1 to Ex-9.
    stationNames <- paste0('Ex-',1:9)

    #All options shown below.
    #layoutMatrix starting from top left (NW) to bottom right (SE) by row.
    layoutMatrix(stationNames = stationNames,
                 start = 'topleft', byrow = TRUE, ncol = 3, nrow = 3)

    #layoutMatrix starting from top left (NW) to bottom right (SE) by column.
    layoutMatrix(stationNames = stationNames,
                 start = 'topleft', byrow = FALSE, ncol = 3, nrow = 3)

    #layoutMatrix starting from top right (NE) to bottom left (SW) by row.
    layoutMatrix(stationNames = stationNames,
                 start = 'topright', byrow = TRUE, ncol = 3, nrow = 3)

    #layoutMatrix starting from top right (NE) to bottom left (SW) by column.
    layoutMatrix(stationNames = stationNames,
                 start = 'topright', byrow = FALSE, ncol = 3, nrow = 3)

    #layoutMatrix starting from bottom left (SW) to top right (NE) by row.
    layoutMatrix(stationNames = stationNames,
                 start = 'bottomleft', byrow = TRUE, ncol = 3, nrow = 3)

    #layoutMatrix starting from bottom left (SW) to top right (NE) by column.
    layoutMatrix(stationNames = stationNames,
                 start = 'bottomleft', byrow = FALSE, ncol = 3, nrow = 3)

    #layoutMatrix starting from bottom right (SE) to top left (NW) by row.
    layoutMatrix(stationNames = stationNames,
                 start = 'bottomright', byrow = TRUE, ncol = 3, nrow = 3)

    #layoutMatrix starting from bottom right (SE) to top left (NW) by column.
    layoutMatrix(stationNames = stationNames,
                 start = 'bottomright', byrow = FALSE, ncol = 3, nrow = 3)

Create a heatmap to visualize localization output.

Description

This function can be used to create a heatmap from the localization grid search. In general, this function should only be used internally, but it could be useful for making customized figures.

Usage

locHeatmap(SearchMap, SMap, NodeInfo, location, mar)

Arguments

Value

No return value.

Examples

    
    #Get filepaths for example data.
    fp <- list.files(system.file('extdata', package = 'locaR'), pattern = '.mp3', full.names = TRUE)
    #Add names.
    names(fp) <- sapply(strsplit(basename(fp), '_'), '[[', 1)
    #Load first row of detection data.
    row <- read.csv(system.file('extdata',
         'Vignette_Detections_20200617_090000.csv', package = 'locaR'),
          stringsAsFactors = FALSE)[1,]
    #Get non-empty Station columns.
    stationSubset <- unlist(row[1,paste0('Station',1:6)])
    stationSubset <- stationSubset[!is.na(stationSubset) & stationSubset != '']
    #Create wav list.
    wl <- createWavList(paths = fp[stationSubset], names = stationSubset,
           from = row$From, to = row$To, buffer = 0.2, index=1)
    #Read coordinates.
    coordinates <- read.csv(system.file('extdata',
                            'Vignette_Coordinates.csv', package = 'locaR'),
                             stringsAsFactors = FALSE)
    row.names(coordinates) <- coordinates$Station
    #Subset coordinates.
    crd <- coordinates[stationSubset,]
    #Localize.
    loc <- localize(wavList = wl, coordinates = crd, locFolder = tempdir(),
               F_Low = row$F_Low, F_High = row$F_High,
               jpegName = '0001.jpeg', keep.SearchMap = TRUE)
    #Convert crd (coordinates) to matrix called NodePos.
    NodePos <- as.matrix(crd[,c('Easting', 'Northing', 'Elevation')])
    colnames(NodePos) <- c('Easting', 'Northing', 'Elevation')
    row.names(NodePos) <- crd$Station
    #Plot heatmap with locHeatmap().
    locHeatmap(SearchMap = loc$SearchMap, SMap = loc$SMap,
                NodeInfo = list(Num = 5, Pos = NodePos), location = loc$location,
                mar = c(0,0,0,0))
    

locaR: A Set of Tools for Sound Localization.

Description

The locaR package contains functions for localizing sounds using R. Localizations are carried out using the modified steered response power algorithm of Cobos et al. (2011) which carries out a grid-search to find the location in three dimensions where a sound was most likely to have originated.

References

Cobos, M., Martí, A., & J.J. López. 2011. A modified SRP-PHAT functional for robust real-time sound source localization with scalable spatial sampling. IEEE Signal Processing Letters. 18:71-74. doi:10.1109/LSP.2010.2091502.

Localize detected sounds

Description

localize and the related function localizeMultiple are the basic functions for localizing sounds. They take audio data as inputs, alongside relevant metadata (e.g. coordinates and a variety of settings), and estimate the location of the dominant sound source. The localize function takes as arguments the minimal amount of information needed for localization. Localization is conducted on the full duration of the Wave objects in wavList. Effectively this means the user must wrangle the data and clip the audio themselves, but this affords the greatest flexibility in terms of how the user chooses to organize their data. The localizeMultiple function, in contrast, automates much of the data wrangling process, but requires data to be organized in a very specific way (e.g. folder structure, file structures). Thus, the latter function trades off flexibility for increased automation. Both functions use the same underlying localization algorithm - localizeMultiple passes its data to localize after the data has been wrangled.

Usage

localize(
  wavList,
  coordinates,
  margin = 10,
  zMin = -1,
  zMax = 20,
  resolution = 1,
  F_Low = 2000,
  F_High = 8000,
  tempC = 15,
  soundSpeed,
  plot = TRUE,
  locFolder,
  jpegName = "000.jpeg",
  InitData = NULL,
  keep.InitData = TRUE,
  keep.SearchMap = FALSE
)

localizeMultiple(st, indices = "all", plot = TRUE, InitData = NULL)

Arguments

Value

List, containing the location of the sound source (global maximum), and optionally the InitData and SearchMap lists.

References

Cobos, M., Martí, A., & J.J. López. 2011. A modified SRP-PHAT functional for robust real-time sound source localization with scalable spatial sampling. IEEE Signal Processing Letters. 18:71-74. doi:10.1109/LSP.2010.2091502.

Examples

    
    ## example for localize()
    #Get filepaths for example data.
    fp <- list.files(system.file('extdata', package = 'locaR'), pattern = '.mp3', full.names = TRUE)
    #Add names.
    names(fp) <- sapply(strsplit(basename(fp), '_'), '[[', 1)
    #Load first row of detection data.
    row <- read.csv(system.file('extdata',
         'Vignette_Detections_20200617_090000.csv', package = 'locaR'),
          stringsAsFactors = FALSE)[1,]
    #Get non-empty Station columns.
    stationSubset <- unlist(row[1,paste0('Station',1:6)])
    stationSubset <- stationSubset[!is.na(stationSubset) & stationSubset != '']
    #Create wav list.
    wl <- createWavList(paths = fp[stationSubset], names = stationSubset,
           from = row$From, to = row$To, buffer = 0.2, index=1)
    #Read coordinates.
    coordinates <- read.csv(system.file('extdata', 'Vignette_Coordinates.csv',
                                        package = 'locaR'), stringsAsFactors = FALSE)
    row.names(coordinates) <- coordinates$Station
    #Subset coordinates.
    crd <- coordinates[stationSubset,]
    #Localize.
    loc <- localize(wavList = wl, coordinates = crd, locFolder = tempdir(),
               F_Low = row$F_Low, F_High = row$F_High,
               jpegName = '0001.jpeg', keep.SearchMap = TRUE)

    ## Example for localizeMultiple().
    #list mp3 files.
    f.in <- list.files(system.file('extdata', package = 'locaR'), full.names = TRUE, 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'
    #Convert mp3 to wav, as required for this particular example.
    for(i in 1:length(f.in)) {
      y <- tuneR::readMP3(f.in[i])
      tuneR::writeWave(y, filename = f.out[i])
    }
    #Set up survey.
    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)
    #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 = FALSE)
    #Process settings.
    st <- processSettings(settings = survey, getFilepaths = TRUE, types = 'wav')
    #localize
    locs <- localizeMultiple(st = st, indices = 1:2)
    

Localize detected sounds

Description

localizeSingle is an internal function implemented within localizeMultipe. Its basic function is to take an index value corresponding to a detection, extract that detection, extract the relevant coordinates, and feed all relevant metadata into the 'localize()' function.

Usage

localizeSingle(
  st,
  index,
  plot = TRUE,
  InitData = NULL,
  keep.InitData = TRUE,
  keep.SearchMap = FALSE
)

Arguments

Value

List, containing the location of the sound source (global maximum), and optionally the InitData and SearchMap lists.

Create a grid over which to search for sound sources.

Description

makeSearchMap creates the three-dimensional array over which to search for sound sources.

Usage

makeSearchMap(
  easting,
  northing,
  elevation,
  margin = 10,
  zMin = -1,
  zMax = 10,
  resolution = 1
)

Arguments

Details

The localization algorithms used in this package can search for sound sources over areas with arbitrary size and with arbitrary resolution. However, speed can sometimes be slow. Generally speaking, the speed of localization calculations correlates directly with the number of grid cells to be searched. Speed can therefore be increased by searching a smaller area (i.e. by reducing the margin, increasing zMin, or decreasing zMax), or by searching with a coarser grain (i.e. by increasing the resolution).

The final list defining the search map includes three arrays containing x, y and z coordinates of each grid cell, as well as the resolution and range of values in the x, y and z directions. This list is passed to other functions for localization.

Value

A list defining the search map.

Examples

    #read coordinates.
    coords <- read.csv(system.file('extdata', 'Vignette_Coordinates.csv', package = 'locaR'),
       stringsAsFactors = FALSE)
    #make search map.
    sm <- makeSearchMap(easting = coords$Easting,
                       northing = coords$Northing,
                       elevation = coords$Elevation)

Generate grid of spectrograms for detecting sounds of interest.

Description

omniSpectro creates a grid of time-synchronized spectrograms, to facilitate the manual detection of birds across a microphone array. By opening the resulting jpeg images in an image viewing program (e.g. the standard Microsoft Photos app), short clips of sounds can be viewed across an entire microphone array at once. The authors of this package have found this to be an efficient way to view spectrograms, while effectively eliminating the likelihood of double-counting sound sources that may be clearly detectable on many microphones at the same time. At the present time, this function only works when a settings object, st, is provided.

Usage

omniSpectro(st, lm, intervalLength = 5, intervals = "all")

Arguments

Value

No return value.

Examples

    
    #First need to convert mp3 example data to wav.
    #list mp3 files.
    f.in <- list.files(system.file('extdata', package = 'locaR'), full.names = TRUE, 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'
    #Convert mp3 to wav, as required for this particular example.
    for(i in 1:length(f.in)) {
      y <- tuneR::readMP3(f.in[i])
      tuneR::writeWave(y, filename = f.out[i])
    }
    #Set up survey.
    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)
    #Process settings.
    st <- processSettings(settings = survey, getFilepaths = TRUE, types = 'wav')
    #Set up layout matrix.
    lm <- layoutMatrix(st = st, start = 'topleft', byrow = TRUE, nrow = 3, ncol = 3)
    #create detection spectrograms.
    omniSpectro(st, lm, intervalLength = 7)
    

Parse Wildlife Acoustics-type file names.

Description

This function parses the information in file names that are structured according to Wildlife Acoustics' naming convention. Specifically, the format prefix_date_time.wav or prefix_mic_date_time.wav.

Usage

parseWAFileNames(filenames)

Arguments

Value

A data frame with prefix, channels, date, time and extension information.

Process settings file to extract relevant information.

Description

processSettings reads information from a settings file (csv) and combines them into a list for subsequent localization.

Usage

processSettings(settingsFile, settings, getFilepaths = FALSE, types = "wav")

Arguments

Value

A list with information needed for sound localization, including microphone coordinates, the existing detections, channels to use for each recording unit, and information specifying the size and resolution of the grid within which to localize sound sources.

Examples

    #Read example data
    settings <- read.csv(system.file('extdata', 'Ex_20200617_090000_Settings.csv',
                                     package = 'locaR'), stringsAsFactors = FALSE)

    #Over-write default values for SiteWavsFolder, CoordinatesFile, and ChannelsFile
    settings$Value[settings$Setting == 'SiteWavsFolder'] <-
                   system.file('extdata', package = 'locaR')
    settings$Value[settings$Setting == 'CoordinatesFile'] <-
                   system.file('extdata', 'Vignette_Coordinates.csv', package = 'locaR')
    settings$Value[settings$Setting == 'ChannelsFile'] <-
                   system.file('extdata', 'Vignette_Channels.csv', package = 'locaR')

    #Run processSettings() function
    st <- processSettings(settings = settings, getFilepaths = FALSE)

Set up a new "survey" with a standardized structure recognized by the package.

Description

setupSurvey sets up the folder structure for a new "survey", which corresponds to a single recording session. By setting up a standardized folder structure, the package functions can carry out much of the data wrangling automatically using the localizeSingle and localizeMultiple functions. The extra work required to set up surveys in a standard format can save time later on.

Usage

setupSurvey(
  folder,
  projectName,
  run = 1,
  coordinatesFile,
  siteWavsFolder,
  adjustmentsFile,
  channelsFile,
  date,
  time,
  tempC = 15,
  soundSpeed,
  surveyLength,
  margin = 10,
  zMin = -1,
  zMax = 20,
  resolution = 1,
  buffer = 0.2
)

Arguments

Value

data.frame containing the settings generated using createSettings. This data.frame is identical to that produced by reading the settingsFile csv, which is also written to file.

Examples

    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)

Get paths for standardized survey workflow.

Description

Function that takes arguments of a base folder and a project name, date, time, and run, and returns the appropriate filepaths for a standardized survey workflow.

Usage

surveyPaths(folder, projectName, date, time, run)

Arguments

Value

Named vector of paths to surveyFolder, runFolder, specFolder, locFolder, detectionsFile, channelsFile, and settingsFile.

Examples

    surveyPaths(folder = tempdir(), projectName = 'Ex', date = '20200617', time = '090000', run = 1)

Create validation spectrograms.

Description

This function is used inside the localize function to create the panels of synchronized spectrograms for manual review.

Usage

validationSpec(
  wavList,
  coordinates,
  locationEstimate,
  from,
  to,
  tempC = 15,
  soundSpeed,
  F_Low,
  F_High
)

Arguments

Value

No return value.

Examples

    
    #Get filepaths for example data.
    fp <- list.files(system.file('extdata', package = 'locaR'),
                      pattern = '.mp3', full.names = TRUE)
    #Add names.
    names(fp) <- sapply(strsplit(basename(fp), '_'), '[[', 1)
    #Load first row of detection data.
    row <- read.csv(system.file('extdata',
         'Vignette_Detections_20200617_090000.csv', package = 'locaR'),
          stringsAsFactors = FALSE)[1,]
    #Get non-empty Station columns.
    stationSubset <- unlist(row[1,paste0('Station',1:6)])
    stationSubset <- stationSubset[!is.na(stationSubset) & stationSubset != '']
    #Create wav list.
    wl <- createWavList(paths = fp[stationSubset], names = stationSubset,
           from = row$From, to = row$To, buffer = 0.2, index=1)
    #Read coordinates.
    coordinates <- read.csv(system.file('extdata', 'Vignette_Coordinates.csv',
                            package = 'locaR'), stringsAsFactors = FALSE)
    row.names(coordinates) <- coordinates$Station
    #Subset coordinates.
    crd <- coordinates[stationSubset,]
    #Localize.
    loc <- localize(wavList = wl, coordinates = crd, locFolder = tempdir(),
               F_Low = row$F_Low, F_High = row$F_High, jpegName = '0001.jpeg',
               keep.SearchMap = TRUE)
    #Create validation spectrogram.
    #Store old par
    oldpar <- par()$mfrow
    par(mfrow = c(6,1))
    validationSpec(wavList = wl, coordinates = crd, locationEstimate = loc$location,
                                 F_Low = row$F_Low, F_High = row$F_High)
    #Reset old par values.
    par(mfrow = oldpar)