Acoustic template detection from time-frequency cross-correlations

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,
  save.txt = FALSE,
  resume = FALSE,
  path = "."
)

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.

save.txt

Logical argument to control if a '.txt' file in selection table format (compatible with the Raven Pro acoustic analysis software) is saved (using exp_raven internally). If so a single file will be saved for each template/sound file combination in the directory given by 'path', overwriting any previous file for that combination. For combinations with no detections the file will still be saved but without any data. The name of the selection will contain the name of the sound file. This is useful for long processes in which users might want to stop and resume or when adding new sound files (see 'resume' argument).

resume

Logical argument to control if detection is skipped for template/sound file combinations that already have a '.txt' file saved (from a previous call with 'save.txt = TRUE'), reading the previous results back in instead of recomputing them. Default is FALSE, meaning detection is always run with the current arguments. Only set to TRUE to resume an interrupted run (or add new sound files) using the exact same detection parameters as the previous call; otherwise stale results from a previous call can be silently returned.

path

Character string containing the directory path where the '.txt' files will be saved (only if save.txt = TRUE). Default is "." (current working directory).

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. Template/sound file combinations with no detections are not included in the output (a data frame with 0 rows is returned if nothing is detected).

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

Author

Marcelo Araya-Salas marcelo.araya@ucr.ac.cr)

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)
}
#>   detections true.positives false.positives false.negatives splits merges
#> 1         77             19              58               0      0      0
#>    overlap recall precision   f.score
#> 1 0.888793      1 0.2467532 0.3958333