findPeaks {monitoR}

Find Score Peaks and Detections in a templateScores Object

Description

This function accepts templateScores objects and returns information on all score peaks and those peaks that are considered detections.

Usage

findPeaks(score.obj, fd.rat = 1, frame, parallel = FALSE)
  

Arguments

score.obj

A templateScores object, produced by corMatch or binMatch.

fd.rat

A ratio of frame width (twice minimum peak separation) to template duration.

frame

If you want the same frame width for templates with varying duration, specify a value directly. fd.rate will be ignored if frame is specified.

parallel

Set to TRUE for parallel processing using mclapply. This option is not available for Windows operating systems.

Details

The findPeaks function translates raw scores from template matching to detection information, by finding peaks in the score data, and determining which peaks, if any, exceed the score cutoffs specified in the templates (see the two functions for making templates, makeBinTemplate and makeCorTemplate and templateCutoff for more details on cutoffs).

Value

An S4 object of class templateScores, with the following slots:

survey.name

The file path to the survey that the scores apply to.

survey

The actual survey as a Wave object.

survey.data

A named list with one element per template. Each element is a named list with time-domain results for the survey.

templates

The templates (an S4 object of class corTemplateList or binTemplateList) used to calculate the scores.

scores

A named list with an element for each template. Each element contains the scores for an individual template.

peaks

A named list with peak information (as a data frame) for each template.

detections

A named list with detection information (as a data frame) for each template.

Author(s)

Sasha D. Hafner and Jon Katz

See Also

makeCorTemplate, makeBinTemplate, corMatch, binMatch, getDetections, getPeaks

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)

# Finally, find peaks and detections
cdetects <- findPeaks(cscores)

cdetects

plot(cdetects)

# plotting help:
method?plot('detectionList')

# Binary example
## Not run: 
# Not run because of the time required (maybe 2-5 seconds) Create two templates
wbt <- makeBinTemplate(btnw.fp, amp.cutoff = -30, t.lim = c(1.5, 2.1), frq.lim = c(4.2, 5.6),
                       buffer = 2, name = "w")

obt <- makeBinTemplate(oven.fp, amp.cutoff = -20, t.lim = c(1, 4), frq.lim = c(1, 11), 
                       name = "o")

# Combine them
btemps <- combineBinTemplates(wbt, obt)

# Calculate scores
bscores <- binMatch(survey.fp, btemps)

# Finally, find peaks and detections
bdetects <- findPeaks(bscores)

bdetects

plot(bdetects)

## End(Not run)

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