calculateEchoDepth: Calculate Depth from Echoes

In PAMpal: Load and Process Passive Acoustic Data

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
)

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

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

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"

Author(s)

Taiki Sakai [e-mail]

Examples

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

## End(Not run)

PAMpal documentation built on April 4, 2025, 4:21 a.m.