consensus_detection {ohun}

Remove ambiguous detections

Description

consensus_detection removes ambiguous detections

Usage

consensus_detection(detection, by = "overlap", filter = "max", cores = 1, pb = TRUE)

Arguments

detection

Data frame or selection table (using the warbleR package's format, see selection_table) with the output of label_detection containing the start and end of the signals. Must contained at least the following columns: "sound.files", "selec", "start", "end" and "detection.class" (the last one is generated by label_detection). It must also contained the column indicated in the 'by' argument (which is 'overlap' by default).

by

Character vector of length 1 indicating a column in 'detection' that will be used to filter detections. Must refer to a numeric column. Default is 'overlap', which is return by label_detection.

filter

Character vector of length 1 indicating the criterium used to filter the column refer to by the 'by' argument. Current options are 'max' (maximum) and 'min' (minimum). Default is 'max'.

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

Details

This function removes ambiguous detections keeping only the one that maximizes a criterium given by 'filter'. By default it keeps the detection with the highest overlap to the reference signal. It works on the output of label_detection. Useful when several detections match the same reference as in the case of template detection with multiple templates (see template_detector).

Value

A data frame or selection table (if 'detection' was also a selection table, warbleR package's format, see selection_table) as in 'X' but removing ambiguous detections (split and merged positives).

Author(s)

Marcelo Araya-Salas ([e-mail]).

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

label_detection, template_detector

Examples

{
  # load example data
  data("lbh1", "lbh_reference")

  # save sound files
  tuneR::writeWave(lbh1, 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 = "lbh2.wav"
  )

  # template detection
  td <- template_detector(template.correlations = tc, threshold = 0.12)

  # this detection generates 2 split positives
  diagnose_detection(
    reference = lbh_reference[lbh_reference == "lbh2.wav", ],
    detection = td
  )

  # label detection
  ltd <- label_detection(
    reference = lbh_reference[lbh_reference == "lbh2.wav", ],
    detection = td
  )

  # now they can be filter to keep the detection with the highest score for each split
  ftd <- consensus_detection(ltd, by = "scores")

  # splits must be 0
  diagnose_detection(
    reference = lbh_reference[lbh_reference == "lbh2.wav", ],
    detection = ftd
  )
}