warbleR (version 1.1.26)

color_spectro: 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.

Value

A plot is produced in the graphic device.

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

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.

See Also

track_freq_contour for creating spectrograms to visualize frequency measurements by spectro_analysis, snr_spectrograms for creating spectrograms to optimize noise margins used in sig2noise

Other spectrogram creators: freq_DTW(), multi_DTW(), phylo_spectro(), snr_spectrograms(), spectrograms(), track_freq_contour()

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)
# }
# NOT RUN {
# }