PAMpal (version 1.4.4)

calculateEchoDepth: Calculate Depth from Echoes

Description

Calculate the estimated depth of echolocation clicks using surface reflected echoes. This uses the time delay between the received signal and its surface echo to estimate the depth of a calling animal. Requires that a set of waveform clips has been created using writeEventClips, and that events have been localized.

Usage

calculateEchoDepth(
  x,
  wav,
  clipLen = 0.03,
  spParams = NULL,
  soundSpeed = 1500,
  hpDepthError = 1,
  locType = "PGTargetMotion",
  plot = TRUE,
  nPlot = 400,
  nCol = 5,
  plotDir = NULL,
  plotIci = TRUE,
  maxIci = 2.5,
  sr = NULL,
  progress = TRUE,
  verbose = TRUE
)

Value

the AcousticStudy object x with estimated dive depth outputs added for each detection that had a matching wav clip file in wav. Detections that either did not have matchinf wav files or did not have localizations will have NA for all dive depth outputs. The depth outputs are

maxTime

Delay time with maximum correlation value

pair2Time

Delay time with second highest correlation value

pair3Time

Delay time with third highest correlation value

maxMag

Correlation magnitude for "maxTime"

pair2Mag

Correlation magnitude for "pair2Time"

pair3Mag

Correlation magnitude for "pair3Time"

maxDepth

Calculated depth for "maxTime"

pair2Depth

Calculated depth for "pair2Time"

pair3Depth

Calculated depth for "pair3Time"

Arguments

x

AcousticStudy object

wav

either folder containing wave clips or list of wave clip files

clipLen

length (seconds) of clip to analyze

spParams

list of species-specific parameters, see details

soundSpeed

sound speed (meters/second) to use for calculations

hpDepthError

maximum error (meters) in hydrophone depth measurement

locType

name of localization, note that this function is not computing any localization, only using previously calculated

plot

logical flag to create summary plots

nPlot

number of waveform plots to create for summary

nCol

number of columns for waveform summary plot

plotDir

directory to store plot outputs, default NULL will result in no plots being created

plotIci

logical flag to additionally create ICI plots

maxIci

maximum allowed ICI value (seconds)

sr

if not NULL (default), clips in wav will be decimated to match this sample rate

progress

logical flag to show progress bar

verbose

logical flag to show messages

Author

Taiki Sakai

Details

spParams allows for species-specific filtering and acceptable echo time delays to be specified. These are provided as a list with elements freqLow and freqHigh specifying the lower and upper ends of a bandpass filter to apply to the signals (in Hz), which can aid in properly detecting the echoes. Parameters minTime and maxTime can also be supplied to define ranges on allowed time delay values. Alternatively if maxTime is NULL or not present it will be calculated from the hydrophone geometry, and minTime can be calculated from geometry by providing minDepth and maxRange as the minimum detectable depth and maximum detectable range (in meters).

If the same values for these parameters should be used for all detections in x, then spParams can be provided as a list with each parameter named, e.g.

  list(freqLow=10e3, freqHigh=50e3, minTime=.001, maxTime=NULL)

If different values should be used for different species, then spParams must be a named list where the names match the species in x, providing a separate list of values for each species. e.g.

  list(Zc=list(freqLow=10e3, freqHigh=50e3, minTime=.001, maxTime=NULL),
       Pm=list(freqLow=2e3, freqHigh=16e3, minTime=.001, maxTime=NULL))

Examples

# example not run because it requires access to large files not present
# in the package testing material
if (FALSE) {
study <- addRecordings(study, folder='path/to/recordings')
wavPath <- 'path/to/wavFiles'
writeEventClips(study, outDir=wavPath, mode='detection')
study <- calculateEchoDepth(study, wav=wavPath)
}