calculateAverageSpectra {PAMpal}

Calculate Average Spectra of Clicks

Description

Calculates the average spectra of all the clicks present in an event

Usage

calculateAverageSpectra(
  x,
  evNum = 1,
  calibration = NULL,
  wl = 512,
  channel = 1:2,
  filterfrom_khz = 0,
  filterto_khz = NULL,
  sr = NULL,
  snr = 0,
  norm = TRUE,
  plot = TRUE,
  noise = FALSE,
  decimate = 1,
  sort = FALSE,
  mode = "spec",
  title = NULL,
  ylim = NULL,
  flim = NULL,
  cmap = hcl.colors(30, "YlOrRd", rev = TRUE),
  brightness = 0,
  contrast = 0,
  q = 0.01,
  showBreaks = TRUE,
  ...
)

Arguments

x

an AcousticEvent or AcousticStudy object

evNum

if x is a study, the event index number to calculate the average spectra for. Note that this is the index in the order that they appear in the AcousticStudy object, not the actual event number. Alternatively full event names can be used

calibration

a calibration function to apply, if desired

wl

the size of the click clips to use for calculating the spectrum. If greater than the clip present in the binary, clip will be zero padded

channel

channel(s) to include in calculations. Currently does not correspond to actual channel in instrument, just the order present in the binary file

filterfrom_khz

frequency in khz of highpass filter to apply, or the lower bound of a bandpass filter if filterto_khz is not NULL

filterto_khz

if a bandpass filter is desired, set this as the upper bound. If only a highpass filter is desired, leave as the default NULL value. Currently only highpass and bandpass filters are supported, so if filterfrom_khz is left as zero then this parameter will have no effect

sr

a sample rate to use if the sample rate present in the database needs to be overridden (typically not needed)

snr

minimum signal-to-noise ratio to be included in the average, in dB. SNR is calculated as difference between the signal and noise spectra at the peak frequency of the signal. This can be inaccurate if noise is inaccurate (see noise for issues with noise calculations)

norm

logical flag to normalize dB magnitude to maximum of 0

plot

logical flag whether or not to plot the result. This will create two plots, the first is a concatenated spectrogram where the y-axis is frequency and the x-axis is click number. The second plot is the average spectrogram of all clicks, the y-axis is dB, x-axis is frequency. Can be a vector of length two to create only one of the two plots

noise

logical flag to plot an average noise spectrum. This is estimated by taking a window of length wl immediately before click. Since there are only a limited number of samples saved in the Pamguard binary files, this can be very inaccurate when wl is a large proportion of the total samples saved. In these cases the noise floor will appear nearly identical to the signal, reducing wl can help get a more accurate noise floor.

decimate

integer factor to reduce sample rate by

sort

logical flag to sort concatenated spectrogram by peak frequency

mode

one of 'spec' or 'ceps' to plot the spectrum or cepstrum

title

replacement titles for plots, can be length vector of length two to provide separate titles

ylim

optional y limits for mean spectra plot

flim

optional frequency limits for both plots

cmap

colors to use for concatenated click spectrogram, either a palette function or vector of colors

brightness

value from -255 to 255, positive values increase brightness, negative values decrease brightness of concatenated spectrogram image

contrast

value from -255 to 255, positive values increase contrast, negative values decrease contrast of concatenated spectrogram image

q

lower and upper quantiles to remove for scaling concatenated spectrogram. Or if a single value, then quantiles q and 1-q will be used. Ex. if q=.01, then the bottom 1 plotting the image. This is done purely for cosmetic reasons, no output data is affected

showBreaks

logical flag to show lines separating events when plotting multiple events

...

optional args

Value

invisibly returns a list with six items: freq - the frequency, UID - the UID of each click, avgSpec - the average spectra of the event, allSpec - the individual spectrum of each click in the event as a matrix with each spectrum in a separate column, avgNoise - the average noise spectra, allNoise - the individual noise spectrum for each click

Author(s)

Taiki Sakai [e-mail]

Examples

data(exStudy)
# need to update binary file locations to users PAMpal installation
binUpd <- system.file('extdata', 'Binaries', package='PAMpal')
dbUpd <- system.file('extdata', package='PAMpal')
exStudy <- updateFiles(exStudy, bin = binUpd, db=dbUpd)
avSpec <- calculateAverageSpectra(exStudy)
str(avSpec$avgSpec)
range(avSpec$freq)
str(avSpec$allSpec)