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

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.

Value

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

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

Examples

Run this code

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