plotGram {PAMpal}

Plot Spectrogram or Cepstrogram

Description

Plots either a spectrogram or cepstrogram and also overlays whistle or cepstral contours from the binary files

Usage

plotGram(
  x,
  evNum = 1,
  start = NULL,
  end = NULL,
  channel = 1,
  wl = 512,
  hop = 0.25,
  mode = c("spec", "ceps"),
  detections = c("cepstrum", "click", "whistle"),
  detCol = c("red", "blue", "purple"),
  brightness = 0,
  contrast = 0,
  q = 0.01,
  cmap = gray.colors(64, start = 1, end = 0),
  size = 1,
  add = FALSE,
  title = NULL,
  sr = NULL,
  freqRange = NULL,
  ...
)

Arguments

x

an AcousticStudy object

evNum

if x is a study, the event index number to plot. 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

start

start time of the plot, either POSIXct or seconds from the start of the event

end

end time of the plot, either POSIXct or seconds from the start of the event.

channel

channel to plot

wl

window length of FFT to use for creating plot

hop

hop value of FFT to use for creating plot, either as a percentage of wl or number of samples

mode

one of 'spec' or 'ceps' to plot either spectrogram or cepstrogram

detections

vector containing any of 'cepstrum', 'click', and/or 'whistle' indicating which detections to overlay on the plot

detCol

vector containing colors to use for plotting detections. Order matches order of detections (default alphabetical - cepstrum, click, whistle)

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

cmap

color map for the spectrogram, either a palette function or vector of colors

size

size scaling to apply to plotted points and lines, as a multiple factor to the default values. Can be a vector of length equal to detections to apply different size scales

add

logical flag FALSE to create a new plot (default), or TRUE to only add new detections to an existing plotGram plot with the same parameters. Can be used to add detections with different visual parameters for the same detection type (e.g. clicks with different point size and color). Typically will only work well if start and end have been set manually.

title

optional title for plot, defaults to "Spectrogram" or "Cepstrogram"

sr

sample rate to decimate to

freqRange

frequency range to plot, in Hz for mode='spec' or milliseconds for mode='ceps'

...

additional arguments to pass to points or lines

Value

nothing, just plots

Author(s)

Taiki Sakai [e-mail]

Examples

data(exStudy)
recs <- system.file('extdata', 'Recordings', package='PAMpal')
exStudy <- updateFiles(exStudy,
                       bin=system.file('extdata', 'Binaries', package='PAMpal'),
                       db = system.file('extdata', 'Example.sqlite3', package='PAMpal'))
exStudy <- addRecordings(exStudy, folder=recs, log=FALSE, progress=FALSE)
# No detections will appear on plot because included recordings are heavily decimated
plotGram(exStudy)