.getSurprisal: Get surprisal per sound

Description

Internal soundgen function called by getSurprisal.

Usage

.getSurprisal(
  audio,
  winSurp,
  input = c("audSpec", "env", "spectrogram", "pspec", "melspec")[1],
  takeLog = TRUE,
  audSpec_pars = list(filterType = "butterworth", nFilters = 32, step = 20, yScale =
    "bark"),
  spec_pars = list(windowLength = c(5, 40), step = NULL),
  env_pars = list(windowLength = 40, step = 20),
  melfcc_pars = list(windowLength = 25, step = 5, maxfreq = NULL, nbands = NULL),
  method = c("acf", "np")[1],
  sameLagAllFreqs = FALSE,
  weightByAmpl = TRUE,
  weightByPrecision = TRUE,
  onlyPeakAutocor = TRUE,
  rescale = FALSE,
  plot = TRUE,
  osc = c("none", "linear", "dB")[2],
  heights = c(3, 1),
  ylim = NULL,
  contrast = 0.2,
  brightness = 0,
  maxPoints = c(1e+05, 5e+05),
  padWithSilence = TRUE,
  colorTheme = c("bw", "seewave", "heat.colors", "...")[1],
  col = NULL,
  extraContour = NULL,
  xlab = NULL,
  ylab = NULL,
  xaxp = NULL,
  mar = c(5.1, 4.1, 4.1, 2),
  main = NULL,
  grid = NULL,
  width = 900,
  height = 500,
  units = "px",
  res = NA,
  ...
)

Arguments

winSurp: surprisal analysis window, ms (Inf = from sound onset)
input: audSpec = auditory spectrogram (audSpectrogram, speed with default settings ~= 1x), spectrogram = STFT spectrogram with (spectrogram, speed ~= 0.25x), pspec = STFT power spectrogram with (melfcc, speed ~= 0.2x), melspec = STFT mel-spectrogram with (melfcc, speed ~= 0.45x), env = analytic envelope (getRMS, speed ~= 27x) Any custom spectrogram-like matrix of features (time in columns labeled in s, features in rows) is also accepted (see examples)
takeLog: if TRUE, the input is log-transformed prior to calculating surprisal. Negative values are treated as in audSpectrogram - note that the chosen dynamic range affects this normalization (the default is 80 dB). If input = audSpec or input = spectrogram, there can be other internal preprocessing like modifying contrast based on audSpec_pars or spec_pars
audSpec_pars, spec_pars, melfcc_pars, env_pars: a list of parameters passed to audSpectrogram (if input = 'audSpec'), spectrogram (if input = 'spectrogram'), melfcc (if input = 'melspec' or 'pspec'), or getRMS (if input = 'env')
method: (for $surprisal only, has no effect on $info and $kl) acf = change in maximum autocorrelation after adding the final point; np = nonlinear prediction (see nonlinPred - works but is VERY slow); none = do not calculate $surprisal to save time and only return $info and $kl
sameLagAllFreqs: (only for method = 'acf') if TRUE, the bestLag is calculated by averaging the ACFs of all channels, and the same bestLag is used to calculate the surprisal in each frequency channel (we expect the same "rhythm" for all frequencies); if FALSE, the bestLag is calculated separately for each frequency channel (we can track different "rhythms" at different frequencies)
weightByAmpl: if TRUE, ACFs and surprisal are weighted by max amplitude per frequency channel
weightByPrecision: if TRUE, surprisal is weighted by the current autocorrelation, so deviations from a previous pattern are more surprising if this pattern is strong
onlyPeakAutocor: if TRUE, only peaks of ACFs are considered (so bestLag can never be 1, and the first change after a string of static values results in surprisal = NA)
rescale: if TRUE, surprisal is normalized from (-Inf, Inf) to [-1, 1]
plot: if TRUE, plots the auditory spectrogram and the suprisalLoudness contour
osc: "none" = no oscillogram; "linear" = on the original scale; "dB" = in decibels
heights: a vector of length two specifying the relative height of the spectrogram and the oscillogram (including time axes labels)
ylim: frequency range to plot, kHz (defaults to 0 to Nyquist frequency). NB: still in kHz, even if yScale = bark, mel, or ERB
contrast: controls the sharpness or contrast of the image: <0 = decrease contrast, 0 = no change, >0 increase contrast. Recommended range approximately (-1, 1). The spectrogram is raised to the power of exp(3 * contrast)
brightness: makes the image lighter or darker: <0 = darker, 0 = no change, >0 = lighter, range (-1, 1). The color palette is preserved, so "brightness" works by capping an increasing proportion of image at the lightest or darkest color. To lighten or darken the palette, just change the colors instead
maxPoints: the maximum number of "pixels" in the oscillogram (if any) and spectrogram; good for quickly plotting long audio files; defaults to c(1e5, 5e5); does not affect reassigned spectrograms
padWithSilence: if TRUE, pads the sound with just enough silence to resolve the edges properly (only the original region is plotted, so the apparent duration doesn't change)
colorTheme: black and white ('bw'), as in seewave package ('seewave'), matlab-type palette ('matlab'), or any palette from palette such as 'heat.colors', 'cm.colors', etc
col: actual colors, eg rev(rainbow(100)) - see ?hcl.colors for colors in base R (overrides colorTheme)
extraContour: a vector of arbitrary length scaled in Hz (regardless of yScale, but nonlinear yScale also warps the contour) that will be plotted over the spectrogram (eg pitch contour); can also be a list with extra graphical parameters such as lwd, col, etc. (see examples)
xlab, ylab, main, mar, xaxp: graphical parameters for plotting
grid: if numeric, adds n = grid dotted lines per kHz
width, height, units, res: graphical parameters for saving plots passed to png
...: other graphical parameters