color_spectro: Highlight spectrogram regions
In warbleR: Streamline Bioacoustic Analysis

color_spectro

R Documentation

Highlight spectrogram regions

Description

color_spectro highlights spectrogram regions specified by users

Usage

color_spectro(
  wave,
  wl = 512,
  wn = "hanning",
  ovlp = 70,
  dB = "max0",
  collevels = NULL,
  selec.col = "red2",
  col.clm = NULL,
  base.col = "black",
  bg.col = "white",
  strength = 1,
  cexlab = 1,
  cexaxis = 1,
  tlab = "Time (s)",
  flab = "Frequency (kHz)",
  title = NULL,
  axisX = TRUE,
  axisY = TRUE,
  flim = NULL,
  rm.zero = FALSE,
  X = NULL,
  fast.spec = FALSE,
  t.mar = NULL,
  f.mar = NULL,
  interactive = NULL,
  add = FALSE
)

Arguments

`wave`	A 'wave' object produced by `readWave` or similar functions.
`wl`	A numeric vector of length 1 specifying the window length of the spectrogram. Default is 512.
`wn`	Character vector of length 1 specifying window name. Default is "hanning". See function `ftwindow` for more options.
`ovlp`	Numeric vector of length 1 specifying the percent overlap between two consecutive windows, as in `spectro`. Default is 70.
`dB`	Character vector of length 1 controlling the amplitude weights as in `spectro`. Default is 'max0'.
`collevels`	Numeric. Levels used to partition amplitude range as in `spectro`. Default is `NULL`.
`selec.col`	Character vector of length 1 specifying the color to be used to highlight selection. See 'col.clm' for specifying unique colors for each selection. Default is 'red2'. Ignored if 'col.cm' and 'X' are provided.
`col.clm`	Character vector of length 1 indicating the name of the column in 'X' that contains the color names for each selection. Ignored if `X == NULL` or `interactive != NULL`. Default is `NULL`.
`base.col`	Character vector of length 1 specifying the color of the background spectrogram. Default is 'black'.
`bg.col`	Character vector of length 1 specifying the background color for both base and highlighted spectrograms. Default is 'white'.
`strength`	Numeric vector of length 1 controlling the strength of the highlighting color (actually how many times it is repeated in the internal color palette). Must be a positive integer. Default is 1.
`cexlab`	Numeric vector of length 1 specifying the relative size of axis labels. See `spectro`. Default is 1.
`cexaxis`	Numeric vector of length 1 specifying the relative size of axis. See `spectro`. Default is 1.
`tlab`	Character vector of length 1 specifying the label of the time axis.
`flab`	Character vector of length 1 specifying the label of the frequency axis.
`title`	Logical argument to add a title to individual spectrograms. Default is `TRUE`.
`axisX`	Logical to control whether time axis is plotted. Default is `TRUE`.
`axisY`	Logical to control whether frequency axis is plotted. Default is `TRUE`.
`flim`	A numeric vector of length 2 for the frequency limit (in kHz) of the spectrogram, as in `spectro`. Default is `NULL`.
`rm.zero`	Logical indicated if the 0 at the start of the time axis should be removed. Default is `FALSE`.
`X`	Optional. Data frame containing columns for start and end time of signals ('start' and 'end') and low and high frequency ('bottom.freq' and 'top.freq').
`fast.spec`	Logical. If `TRUE` then image function is used internally to create spectrograms, which substantially increases performance (much faster), although some options become unavailable, as collevels, and sc (amplitude scale). This option is indicated for signals with high background noise levels. Palette colors `gray.1`, `gray.2`, `gray.3`, `topo.1` and `rainbow.1` (which should be imported from the package monitoR) seem to work better with 'fast' spectrograms. Palette colors `gray.1`, `gray.2`, `gray.3` offer decreasing darkness levels.
`t.mar`	Numeric vector of length 1. Specifies the margins adjacent to the start and end points to be added when highlighting selection. Default is `NULL`.
`f.mar`	Numeric vector of length 1. Specifies the margins adjacent to the low and high frequencies to be added when highlighting selection. Default is `NULL`.
`interactive`	Numeric. Allow user to interactively select the signals to be highlighted by clicking on the graphic device. Users must select the opposite corners of a square delimiting the spectrogram region to be highlighted. Controls the number of signals that users would be able to select (2 clicks per signal).
`add`	Logical. If `TRUE` new highlighting can be applied to the current plot (which means that the function with `add = FALSE` should be run first). Default is `FALSE`.

Details

This function highlights regions of the spectrogram with different colors. The regions to be highlighted can be provided in a selection table (as the example data 'lbh_selec_table') or interactively ('interactive' argument).

Value

A plot is produced in the graphic device.

Author(s)

Marcelo Araya-Salas (marcelo.araya@ucr.ac.cr) and Grace Smith Vidaurre

References

Araya-Salas, M., & Smith-Vidaurre, G. (2017). warbleR: An R package to streamline analysis of animal acoustic signals. Methods in Ecology and Evolution, 8(2), 184-191.

Examples

## Not run: 
data(list = c("Phae.long1", "lbh_selec_table"))
writeWave(Phae.long1, file.path(tempdir(), "Phae.long1.wav")) # save sound files

# subset selection table
st <- lbh_selec_table[lbh_selec_table$sound.files == "Phae.long1.wav", ]

# read wave file as an R object
sgnl <- tuneR::readWave(file.path(tempdir(), st$sound.files[1]))

# create color column
st$colors <- c("red2", "blue", "green")

# highlight selections
color_spectro(
  wave = sgnl, wl = 300, ovlp = 90, flim = c(1, 8.6), collevels = seq(-40, 0, 5),
  dB = "B", X = st, col.clm = "colors", base.col = "skyblue", t.mar = 0.07, f.mar = 0.1,
  interactive = NULL
)

# interactive (selected manually: you have to select them by clicking on the spectrogram)
color_spectro(
  wave = sgnl, wl = 300, ovlp = 90, flim = c(1, 8.6), collevels = seq(-40, 0, 5),
  dB = "B", col.clm = "colors", t.mar = 0.07, f.mar = 1, interactive = 2
)

## End(Not run)

warbleR documentation built on Sept. 11, 2024, 7:13 p.m.