Remove ambiguous detections

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.

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

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. Mostly useful when several detections match the same reference as in the case of template detection with multiple templates (see template_detector). Keep in mind that the argument 'solve.ambiguous' most be FALSE to keep those ambiguous detections.

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

label_detection, template_detector

Author

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

Examples

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

  # save sound files
  tuneR::writeWave(lbh1, file.path(tempdir(), "lbh1.wav"))

  # template for the first sound file in 'lbh_reference'
  templ1 <- lbh_reference[lbh_reference$sound.files == "lbh1.wav" & lbh_reference$selec == 11, ]

  # generate template correlations
  tc <- template_correlator(
    templates = templ1, path = tempdir(),
    files = "lbh1.wav"
  )

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

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

  # label detection
    ltd <- label_detection(
    reference = lbh_reference[lbh_reference == "lbh1.wav", ],
    detection = td, 
    solve.ambiguous = FALSE
    )

  # 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 == "lbh1.wav", ],
    detection = ftd,
    solve.ambiguous = FALSE
  )
}
#> computing correlations (step 0 of 0):
#>   detections true.positives false.positives false.negatives splits merges
#> 1         13             10               3               0      0      0
#>     overlap recall precision   f.score
#> 1 0.8917651      1 0.7692308 0.8695652