showPeaks: View or Verify Detections or Peaks

In jonkatz2/monitoR: Acoustic Template Detection in R

View or Verify Detections or Peaks

Description

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.

Usage

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

Arguments

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.

Details

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

Value

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

Author(s)

Sasha D. Hafner

See Also

findPeaks, plot-methods

Examples

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

jonkatz2/monitoR documentation built on March 27, 2024, 4:39 p.m.