ohun (version 1.0.3)

template_detector: 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
)

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.

Arguments

template.correlations

object of class 'template_correlations' generated by template_correlator containing the correlation score vectors.

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 TRUE.

verbose

Logical argument to control if some summary messages are printed to the console.

Author

Marcelo Araya-Salas )

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.

References

Araya-Salas, M., Smith-Vidaurre, G., Chaverri, G., Brenes, J. C., Chirino, F., Elizondo-Calvo, J., & Rico-Guevara, A. (2023). ohun: An R package for diagnosing and optimizing automatic sound event detection. Methods in Ecology and Evolution, 14, 2259–2271. https://doi.org/10.1111/2041-210X.14170

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)
}