showPeaks: View or Verify Detections or Peaks
In monitoR: Acoustic Template Detection in R

Description Usage Arguments Details Value Author(s) See Also Examples

Use this function to view a spectrogram and score plot of detections or peaks. In its simplest usage, showPeaks will show all detections within for the first template within the detection list object, one after the other. With the verify option (verify = TRUE), the user can tag detections or peaks as TRUE or FALSE, and these results will be saved in an updated detection list object.

showPeaks(detection.obj, which.one = names(detection.obj@templates)[1], fd.rat = 4, 
frame = fd.rat * detection.obj@templates[[which.one]]@duration, id = 1:nrow(pks), 
t.lim, flim = c(0, 20), point = TRUE, ask = if (verify) FALSE else TRUE, 
scorelim = NULL, verify = FALSE, what = "detections", box = TRUE, 
player = "play", spec.col = gray.3(), on.col = '#FFA50075', off.col = '#0000FF75', 
pt.col = '#FFA50075')

`detection.obj`	A detection list object (`detectionList`).
`which.one`	Which template should be shown? Identify by name or position. Length-one integer or character vector.
`fd.rat`	Ratio of plot frame (time duration of plots) to template duration.
`frame`	Or, specify the plot frame (x limits of plots) instead of `fr.rate`. Length-one numeric vector.
`id`	Use to specify which peaks or detections will be shown. Integer vector.
`t.lim`	Or, to view only those detections or peaks within a certain time range, specify it here. Length-two numeric vector.
`flim`	Frequency limits (y axis limits) for the spectrogram. Length-two numeric vector.
`point`	If `TRUE`, plot points to show detection or peak locations.
`ask`	The setting of the `par` setting `ask`. Default value is based on other arguments, and should suffice in most cases.
`scorelim`	Score limits (y axis limits) for the score plot.
`verify`	If `TRUE`, R will prompt user to identify whether detections are `TRUE`
`what`	Should all peaks (`what = "peaks"`) or just detections (`what = "detections"`) be shown?
`box`	If `TRUE` plot a box around detections in the spectrogram. Box boundaries are based on template duration and frequency limits. Can also be set to "template" to see the template points plotted over the detection.
`player`	If `verify = TRUE`, the user will have the option to play the detection or peak. This argument is the command used for starting the player. See Details.
`spec.col`	A vector of colors for the spectrogram.
`on.col`	Colors for the on points of a binary point template, if `box = "template"`. Default is #RRGGBBAA, where AA is the transparency.
`off.col`	Colors for the off points of a binary point template, if `box = "template"`. Default is #RRGGBBAA, where AA is the transparency.
`pt.col`	Colors for the points of a correlation template, if `box = "template"`. Default is #RRGGBBAA, where AA is the transparency.

Note that almost all of the arguments have a default value.
The default audio player, "play", is the shell command for SoX, the multi-OS media player. Windows will detect the file type and use the default media player with "start", or you can specify one (such as Windows Media Player) with "start wmplayer.exe". On Ubuntu try Rhythmbox ("rhythmbox"), and on Mac OS try afplay ("afplay").

NULL, invisibly, or, if verify = TRUE, an updated detection list object (detectionList).

Sasha D. Hafner

findPeaks, plot-methods

# Load data
data(btnw)
data(oven)
data(survey)

# Write Wave objects to file (temporary directory used here)
btnw.fp <- file.path(tempdir(), "btnw.wav")
oven.fp <- file.path(tempdir(), "oven.wav")
survey.fp <- file.path(tempdir(), "survey2010-12-31_120000_EST.wav")
writeWave(btnw, btnw.fp)
writeWave(oven, oven.fp)
writeWave(survey, survey.fp)

# Correlation example
# Create two correlation templates
wct <- makeCorTemplate(btnw.fp, t.lim = c(1.5, 2.1), frq.lim = c(4.2, 5.6), name = "w")
oct <- makeCorTemplate(oven.fp, t.lim = c(1, 4), frq.lim = c(1, 11), dens = 0.1, name = "o")

# Combine them
ctemps <- combineCorTemplates(wct, oct)

# Calculate scores
cscores <- corMatch(survey.fp, ctemps)

# Find peaks and detections
cdetects <- findPeaks(cscores)
cdetects

# Interactively inspect individual detections, no return value
## Not run: 
# Not run because user input is required
showPeaks(detection.obj = cdetects, which.one = "w", flim = c(2, 8), point = TRUE, 
          scorelim = c(0, 1))

# Interactively verify individual detections, return adds verification field
cdetects <- showPeaks(detection.obj = cdetects, which.one = "w", flim = c(0, 20), 
                      point = TRUE, scorelim = c(0, 1), verify = TRUE)

## End(Not run)