template_detector {ohun} | R Documentation |
Acoustic template detection from time-frequency cross-correlations
Description
template_detector
find sound event occurrences in cross-correlation vectors from template_correlator
Usage
template_detector(template.correlations, cores = 1, threshold, pb = TRUE,
verbose = TRUE)
Arguments
template.correlations |
object of class 'template_correlations' generated by |
cores |
Numeric. Controls whether parallel computing is applied. It specifies the number of cores to be used. Default is 1 (i.e. no parallel computing). |
threshold |
Numeric vector of length 1 with a value between 0 and 1 specifying the correlation threshold for detecting sound event occurrences (i.e. correlation peaks). Must be supplied. Correlation scores are forced to between 0 and 1 (by converting negative scores to 0). 0 and 1 represent the lowest and highest similarity to the template respectively. |
pb |
Logical argument to control progress bar. Default is |
verbose |
Logical argument to control if some summary messages are printed to the console. |
Details
This function infers sound events occurrences from cross-correlation scores along sound files. Correlation scores must be generated first using template_correlator
. The output is a data frame (or selection table if sound files are still found in the original path supplied to template_correlator
, using the warbleR package's format, see selection_table
) containing the start and end of the detected sound events as well as the cross-correlation score ('scores' column) for each detection. Note that the detected sounds are assumed to have the same duration as the template, so their start and end correspond to the correlation peak position +/- half the template duration.
Value
The function returns a 'selection_table' (warbleR package's formats, see selection_table
) or data frame (if sound files can't be found) with the start and end and correlation score for the
detected sound events.
Author(s)
Marcelo Araya-Salas marcelo.araya@ucr.ac.cr)
References
Araya-Salas, M., Smith-Vidaurre, G., Chaverri, G., Brenes, J. C., Chirino, F., Elizondo-Calvo, J., & Rico-Guevara, A. 2022. ohun: an R package for diagnosing and optimizing automatic sound event detection. BioRxiv, 2022.12.13.520253. https://doi.org/10.1101/2022.12.13.520253
See Also
energy_detector
, template_correlator
, optimize_template_detector
Examples
{
# load example data
data("lbh1", "lbh2", "lbh_reference")
# save sound files
tuneR::writeWave(lbh1, file.path(tempdir(), "lbh1.wav"))
tuneR::writeWave(lbh2, file.path(tempdir(), "lbh2.wav"))
# template for the first sound file in 'lbh_reference'
templ1 <- lbh_reference[1, ]
# generate template correlations
tc <- template_correlator(templates = templ1, path = tempdir(), files = "lbh1.wav")
# template detection
td <- template_detector(template.correlations = tc, threshold = 0.4)
# diagnose detection
diagnose_detection(
reference =
lbh_reference[lbh_reference$sound.files == "lbh1.wav", ],
detection = td
)
# template for the second and third sound file in 'lbh_reference'
# which have similar song types
templ2 <- lbh_reference[4, ]
# generate template correlations
tc <- template_correlator(
templates = templ2, path = tempdir(),
files = c("lbh1.wav", "lbh2.wav")
)
# template detection
td <- template_detector(template.correlations = tc, threshold = 0.3)
# diagnose detection
diagnose_detection(reference = lbh_reference, detection = td)
}