get_templates {ohun} | R Documentation |
Find templates representative of the structural variation of sound events
Description
get_templates
find the sound events that are closer to the acoustic space centroid (i.e. close to the average acoustic structure) in a reference table.
Usage
get_templates(reference, acoustic.space = NULL, path = ".",
n.sub.spaces = 1, plot = TRUE, color = "#21908C4D", ...)
Arguments
reference |
Selection table (using the warbleR package's format, see |
acoustic.space |
Numeric matrix or data frame with the two dimensions of a custom acoustic space to be used for finding templates. if not supplied the acoustic space is calculated internally (default). Optional. Note that the function assumes that 'reference' and 'acoustic.space' refer to the same sound events and similarly ordered. |
path |
Character string containing the directory path where the sound files are located. The current working directory is used as default. |
n.sub.spaces |
Integer vector of length 1 with the number of sub-spaces to split the total acoustic space. If |
plot |
Logical to control if the plot is created. Default is |
color |
Character string with the point color. Default is '#21908C4D'. |
... |
Additional arguments to be passed to |
Details
This function finds sound events (from a reference table) that are representative of the acoustic structure variation of all sound events. This is done by finding the events closer to the centroid of the acoustic space. If the acoustic space is not supplied ('acoustic.space' argument) then the function will estimate it by measuring several acoustic features using the function spectro_analysis
(features related to energy distribution in the frequency and time domain as well as features of the dominant frequency contours, see spectro_analysis
for more details) and summarizing it with Principal Component Analysis (after z-transforming parameters) using the function prcomp
. Acoustic features with missing values are removed before estimating Principal Component Analysis. The rationale is that a sound event close to the average structure is more likely to share structural features with most events across the acoustic space than a sound event in the periphery of the space.
If only 1 template is required the function returns the sound event closest to the acoustic space centroid. If more than 1 template is required additional sound events are returned that are representative of the acoustic space. To do this, the function defines sub-spaces as equal-size slices of a circle centered at the centroid of the acoustic space. A column 'template' is included in the output selection table that identifies each template. Custom acoustic spaces can be supplied with argument 'acoustic.space'. Notice that the function aims to partition spaces in which sounds are somehow homogeneously distributed. When clear clusters are found in the distribution of the acoustic space thus clusters might not match the sub-spaces defined by the function.
Value
The function returns a 'selection_table' (warbleR package's formats, see selection_table
) or data frame (if sound files can't be found) containing the start and end of each sound event by
sound file.
Author(s)
Marcelo Araya-Salas (marcelo.araya@ucr.ac.cr). Implements a modified version of the timer function from seewave.
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
Examples
{
# Save example files into temporary working directory
data("lbh1", "lbh2", "lbh_reference")
tuneR::writeWave(lbh1, file.path(tempdir(), "lbh1.wav"))
tuneR::writeWave(lbh2, file.path(tempdir(), "lbh2.wav"))
# get a single mean template
template <- get_templates(reference = lbh_reference, path = tempdir())
# get 3 templates
template <- get_templates(reference = lbh_reference, n.sub.spaces = 3, path = tempdir())
}