R: Make an Acoustic Template

makeTemplate {monitoR}

R Documentation

Make an Acoustic Template

Description

Functions for creating a spectrogram cross-correlation template or a binary point matching template for later use in identification of acoustic signals. A template is made by manually or automatically selecting cells within a Fourier-transformed representation (a spectrogram) of an audio recording.

Usage

 

makeCorTemplate(clip, t.lim = NA, frq.lim = c(0, 12), select = "auto", dens = 1,
                score.cutoff = 0.4, name = "A", comment = "", spec.col = gray.3(), 
                sel.col = ifelse(dens == 1, "#99009975", "orange"),
                wl = 512, ovlp = 0, wn = "hanning", write.wav = FALSE, ...)

makeBinTemplate(clip, t.lim = NA, frq.lim = c(0, 12), select = "auto", binary = TRUE, 
                buffer = 0, dens = 1, score.cutoff = 12, name = "A", comment = "", 
                amp.cutoff = "i", shift = "i", high.pass = -Inf, spec.col = gray.3(), 
                bin.col = c("white", "black"), 
                quat.col = c("white", "gray40", "gray75", "black"), 
                sel.col = c("orange", "blue"), legend.bg.col = "#2E2E2E94", 
                legend.text.col = "black", wl = 512, ovlp = 0, wn = "hanning", 
                write.wav = FALSE, ...)

Arguments

`clip`	A file path to one wav or mp3 file, or a Wave object (but see 'Details' for this case). Or, for `makeBinTemplate` only, a list or vector of two such objects. Character vector or list.
`t.lim`	Time limits of the spectrogram plot or template itself, or a list of exactly two such vectors. Length two numeric vector.
`frq.lim`	Frequency limits of spectrogram plot or template. Length two numeric vector.
`select`	How should points be selected? Options are "cell", "rectangle", "auto". Length one character vector.
`binary`	Should plot be binary? Length one logical vector.
`buffer`	The size of a buffer (in number of time by frequency bins) around “on” points for select = "rectangle" and select = "auto" for `makeBinTemplate`. Bins within the buffer will not be included as “on” or “off” points. Length one integer vector.
`dens`	Approximate density of points included with select = "rectangle" and select = "auto" as a fraction of 1.0. Length one numeric vector.
`score.cutoff`	The numeric value set for the `score.cutoff` element of the resulting template. This value will determine which peaks qualify as detections when the resulting template is used in a complete detection analysis. Length one numeric vector.
`name`	The name of the template, which will be associated with the template. To change the name of an existing template, see `templatenames`. Length one character vevetor.
`comment`	Comment that will be saved with the template. See `templateComment`.
`amp.cutoff`	Amplitude cutoff for creating a binary plot. Length one numeric vector or else `"i"` for interactive selection.
`shift`	When two clips are used, the forward shift for the second clip, in time bins. Length one integer vector, or `"i"` for interactive.
`high.pass`	High-pass filter value. All amplitudes below this frequency will be set to the minimum.
`spec.col`	A color palette function for the spectrogram when `binary = FALSE`.
`bin.col`	Colors for the spectrogram when `binary = TRUE`. Length two character vector: `bin.col[1]` for cells below the cutoff, `bin.col[2]` for cells above the cutoff.
`quat.col`	Colors for the spectrogram when using two clips. Length four character vector: `bin.col[1]` for cells below the cutoff for both clips, `bin.col[2]` for cells above the cutoff for clip 1 only, `bin.col[3]` for cells above the cutoff for clip 2 only, `bin.col[4]` for cells above the cutoff for both clips.
`sel.col`	The color for displaying selected cells.
`legend.bg.col`	The color of the legend background.
`legend.text.col`	Legend text color.
`wl`	The `wl` argument sent to the `spectro` function.
`ovlp`	The `ovlp` argument sent to the `spectro` function.
`wn`	The `wn` argument sent to the `spectro` function.
`write.wav`	If `clip` is a `Wave` object, should it be written to file? If `FALSE`, functions will return an error.
`...`	Additional arguments to `spectro`.

Details

makeCorTemplate is used for making correlation templates, while makeBinTemplate is used to make binary point matching templates. makeBinTemplate can be used with one or two recordings (clip argument). If the clip argument is a Wave object, the functions will attempt to write the object(s) to a wav file(s) in the working directory, but only if the write.wav argument is TRUE. To use templates produced with these functions, see corMatch or binMatch. To combine template lists, see combineCorTemplates or combineBinTemplates.

Value

An S4 object of class corTemplateList (returned by makeCorTemplate) or binTemplateList (returned by makeBinTemplate).

Author(s)

Sasha D. Hafner and Jon Katz

References

Mellinger, DK, Clark, CW. 1997. Methods for automatic detection of mysticete sounds. Marine and Freshwater Behaviour and Physiology 29, 163-181.

Towsey M, Planitz, B, Nantes, A, Wimmer, J, Roe, P. 2012. A toolbox for animal call recognition. Bioacoustics 21, 107-125.

Examples

# Load example Wave objects
data(btnw)
data(oven)

# Use a Wave object directly to make a template
## Not run: 
# Not run because it will create a file in user's working directory with write.wav = TRUE
wct1 <- makeCorTemplate(btnw, name = "w1", write.wav = TRUE)
wct1

## End(Not run)

# For traceability, better to use acoustic files
# Here, first write Wave objects to file (temporary directory used here)
btnw.fp <- file.path(tempdir(), "btnw.wav")
oven.fp <- file.path(tempdir(), "oven.wav")
writeWave(btnw, btnw.fp)
writeWave(oven, oven.fp)

# Use default arguments except for name
wct1 <- makeCorTemplate(btnw.fp, name = "w1")

# Specify time and frequency limits to focus on a smaller area
wct2 <- makeCorTemplate(btnw.fp, t.lim = c(1.5, 2.1), frq.lim = c(4.2, 5.6), name = "w2")

# For finer control, see options for select argument, e.g., 
## Not run: 
# Not run because requires user interaction
wct3 <- makeCorTemplate(btnw.fp, select = "cell", name = "w3")
wct4 <- makeCorTemplate(btnw.fp, select = "rectangle", name = "w4")

## End(Not run)

# Use a different recording--different species here
oct1 <- makeCorTemplate(oven.fp, name = "o1", t.lim = c(1, 4), frq.lim = c(1, 11))

# Reduce cell density
oct2 <- makeCorTemplate(oven.fp, name = "o2", t.lim = c(1, 4), frq.lim = c(1, 11), 
                        dens = 0.1)

# Binary templates are similar
# By default, amplitude cutoff is interactively set
## Not run: 
wbt1 <- makeBinTemplate(btnw.fp, name = "w1")

## End(Not run)

# Or specify cutoff directly
wbt1 <- makeBinTemplate(btnw.fp, amp.cutoff = -40, name = "w1")

# Specify time and frequency limits to focus on a smaller area in spectrogram, and add a 
# buffer
## Not run: 
wbt2 <- makeBinTemplate(btnw.fp, amp.cutoff = -30, t.lim = c(1.5, 2.1), 
                        frq.lim = c(4.2, 5.6), buffer = 2, name = "w2")

## End(Not run)

# For finer control, see options for select argument, e.g., 
## Not run: 
# Not run because it requires user input to select cells for the template
wbt3 <- makeBinTemplate(btnw.fp, amp.cutoff = -40, t.lim = c(0.5, 2.5), 
                        frq.lim = c(1, 11), select = "cell", name = "w3")

wbt4 <- makeBinTemplate(btnw.fp, amp.cutoff = -40, t.lim = c(0.5, 2.5), 
                        frq.lim = c(1, 11), select = "rectangle", buffer = 3, name = "w4")

## End(Not run)

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

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

[Package monitoR version 1.0.7 Index]