getDetections: Extract Detections or Peaks from a `detectionList` Object

Description

These functions return detection and peak timing and scores from a detectionList object for one or more templates used to create the object.

Usage

getDetections(detection.obj, which.one = names(detection.obj@detections), id = NULL, 
              output = "data frame")
getPeaks(detection.obj, which.one = names(detection.obj@detections), id = NULL, 
         output = "data frame")

Arguments

detection.obj

The detectionList object.

which.one

The name(s) of the template(s) for which results should be returned. Character vector.

Additional information that will be added as an additional column in the returned data frame(s). By default, no column is added. Length-one vector.

output

Type of output, can be "data frame" or "list". List output contains a single element (a data frame) for each template.

Value

A data frame with up to six (seven for getPeaks) columns: id (from the id argument) (optional), template name (template), date and time (date.time, relative time (relative to the recording start), score, and verification results (true) (only present if the detectionList contains verification results from showPeaks). Or, a list with a separate data frame for each template. For getPeaks, there is also a detection column, with TRUE when a peak has been identified as a detection.

Details

The id argument is for adding an identifying “tag” to the output. This could be useful when, e.g., extracting detections for multiple surveys and then combining all results into a single data frame.

Examples

Run this code

# NOT RUN {
# 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 both of them
ctemps <- combineCorTemplates(wct, oct)

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

# Find peaks
cdetects <- findPeaks(cscores)

# Finally, get detections
getDetections(cdetects)

# If list is preferred
getDetections(cdetects, output = "list")

# For select templates
getDetections(cdetects, which.one = 1)
getDetections(cdetects, which.one = "w")

# Or for all peaks
getPeaks(cdetects)
getPeaks(cdetects, output = "list")
getPeaks(cdetects, which.one = 1)

# Clean up (only because these files were created in these examples)
file.remove(btnw.fp)
file.remove(oven.fp)
file.remove(survey.fp)
# }