Optimize acoustic template detection
Source:R/optimize_template_detector.R
optimize_template_detector.Rdoptimize_template_detector optimizes acoustic template detection
Usage
optimize_template_detector(template.correlations, reference, threshold,
cores = 1, pb = TRUE, by.sound.file = FALSE, previous.output = NULL,
macro.average = FALSE, min.overlap = 0.5)Arguments
- template.correlations
An object of class 'template_correlations' (generated by
template_correlator) in which to optimize detections. Must contain data for all sound files as in 'reference'. It can also contain data for additional sound files. In this case the routine assumes that no sound events are found in those files, so detection from those files are all false positives.- reference
Data frame or 'selection.table' (following the warbleR package format) with the reference selections (start and end of the sound events) that will be used to evaluate the performance of the detection, represented by those selections in 'detection'. Must contained at least the following columns: "sound.files", "selec", "start" and "end". It must contain the reference selections that will be used for detection optimization.
- threshold
Numeric vector of length > 1 with values between 0 and 1 specifying the correlation threshold for detecting sound event occurrences (i.e. correlation peaks). Must be supplied. Several values should be supplied for optimization.
- 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).
- pb
Logical argument to control progress bar and messages. Default is
TRUE.- by.sound.file
Logical to control if diagnostics are calculated for each sound file independently (
TRUE) or for all sound files combined (FALSE, default).- previous.output
Data frame with the output of a previous run of this function. This will be used to include previous results in the new output and avoid recalculating detection performance for parameter combinations previously evaluated.
- macro.average
Logical argument to control if diagnostics are first calculated for each sound file and then averaged across sound files, which can minimize the effect of unbalanced sample sizes between sound files. If
FALSE(default) diagnostics are based on aggregated statistics irrespective of sound files. The following indices can be estimated by macro-averaging: overlap, mean.duration.true.positives, mean.duration.false.positives, mean.duration.false.positives, mean.duration.false.negatives, proportional.duration.true.positives, recall and precision (f.score is always derived from recall and precision). Note that when applying macro-averaging, recall and precision are not derived from the true positive, false positive and false negative values returned by the function.- min.overlap
Numeric. Controls the minimum amount of overlap required for a detection and a reference sound for it to be counted as true positive. Default is 0.5. Overlap is measured as intersection over union.
Value
A data frame in which each row shows the result of a detection job for each cutoff value, including the following diagnostic metrics:
true.positives: number of sound events in 'reference' that correspond to any detection. Matching is defined as some degree of overlap in time. In a perfect detection routine it should be equal to the number of rows in 'reference'.false.positives: number of detections that don't match any of the sound events in 'reference'. In a perfect detection routine it should be 0.false.negatives: number of sound events in 'reference' that were not detected (not found in 'detection'. In a perfect detection routine it should be 0.splits: number of detections overlapping reference sounds that also overlap with other detections. In a perfect detection routine it should be 0.merges: number of sound events in 'detection' that overlap with more than one sound event in 'reference'. In a perfect detection routine it should be 0.recall: Proportion of sound events in 'reference' that were detected. In a perfect detection routine it should be 1.precision: Proportion of detections that correspond to sound events in 'reference' that were detected. In a perfect detection routine it should be 1.
Details
This function takes a a reference data frame or 'selection_table' ('X') and the output of template_correlator and estimates the detection performance for different detection parameter combinations. This is done by comparing the position in time of the detection to those of the reference selections. The function returns several diagnostic metrics to allow user to determine which parameter values provide a detection that more closely matches the selections in 'reference'. Those parameters can be later used for performing a more efficient detection using template_detector. Supported file formats:'.wav', '.mp3', '.flac' and '.wac'.
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
Author
Marcelo Araya-Salas (marcelo.araya@ucr.ac.cr).
Examples
{
# Save sound files to temporary working directory
data("lbh1", "lbh2", "lbh_reference")
tuneR::writeWave(lbh1, file.path(tempdir(), "lbh1.wav"))
tuneR::writeWave(lbh2, file.path(tempdir(), "lbh2.wav"))
# template for the second sound file in 'lbh_reference'
templ <- lbh_reference[11, ]
# generate template correlations
tc <- template_correlator(templates = templ, path = tempdir(),
files = "lbh2.wav")
# using 2 threshold
optimize_template_detector(template.correlations = tc, reference =
lbh_reference[lbh_reference$sound.files == "lbh2.wav", ],
threshold = c(0.2, 0.5))
# using several thresholds
optimize_template_detector(template.correlations = tc,
reference = lbh_reference[lbh_reference$sound.files == "lbh2.wav", ],
threshold = seq(0.5, 0.9, by = 0.05))
# template for the first and second sound file in 'lbh_reference'
templ <- lbh_reference[c(1, 11), ]
# generate template correlations
tc <- template_correlator(templates = templ, path = tempdir(),
files = c("lbh1.wav", "lbh2.wav"))
optimize_template_detector(template.correlations = tc, reference =
lbh_reference, threshold = seq(0.5, 0.7, by = 0.1))
# showing diagnostics by sound file
optimize_template_detector(template.correlations = tc, reference =
lbh_reference,
threshold = seq(0.5, 0.7, by = 0.1), by.sound.file = TRUE)
}
#> 2 thresholds will be evaluated:
#> 9 thresholds will be evaluated:
#> 3 thresholds will be evaluated:
#> 3 thresholds will be evaluated:
#> threshold sound.files templates detections true.positives false.positives
#> 1 0.5 lbh2.wav lbh2.wav-1 9 9 0
#> 2 0.5 lbh1.wav lbh2.wav-1 0 0 0
#> 3 0.5 lbh1.wav lbh1.wav-11 10 10 0
#> 4 0.5 lbh2.wav lbh1.wav-11 0 0 0
#> 5 0.6 lbh2.wav lbh2.wav-1 9 9 0
#> 6 0.6 lbh1.wav lbh2.wav-1 0 0 0
#> 7 0.6 lbh1.wav lbh1.wav-11 10 10 0
#> 8 0.6 lbh2.wav lbh1.wav-11 0 0 0
#> 9 0.7 lbh2.wav lbh2.wav-1 7 7 0
#> 10 0.7 lbh1.wav lbh2.wav-1 0 0 0
#> 11 0.7 lbh1.wav lbh1.wav-11 4 4 0
#> 12 0.7 lbh2.wav lbh1.wav-11 0 0 0
#> false.negatives splits merges overlap recall precision f.score
#> 1 0 0 0 0.8562007 1.0000000 1 1.0000000
#> 2 10 NA NA NA 0.0000000 0 0.0000000
#> 3 0 0 0 0.8917651 1.0000000 1 1.0000000
#> 4 9 NA NA NA 0.0000000 0 0.0000000
#> 5 0 0 0 0.8562007 1.0000000 1 1.0000000
#> 6 10 NA NA NA 0.0000000 0 0.0000000
#> 7 0 0 0 0.8917651 1.0000000 1 1.0000000
#> 8 9 NA NA NA 0.0000000 0 0.0000000
#> 9 2 0 0 0.8436591 0.7777778 1 0.8750000
#> 10 10 NA NA NA 0.0000000 0 0.0000000
#> 11 6 0 0 0.9326121 0.4000000 1 0.5714286
#> 12 9 NA NA NA 0.0000000 0 0.0000000