warbleR (version 1.1.26)

optimize_auto_detec: Optimize the detection of signals based on a-priori detections

Description

Optimize the detection of signals based on a-priori detections

Usage

optimize_auto_detec(X, Y, threshold = 10, power = 1, wl = 512, ssmooth = 0, 
hold.time = 0, mindur = NULL, maxdur = NULL, parallel = 1, pb = FALSE, 
by.sound.file = FALSE, bp = NULL, path = NULL)

Arguments

X

'selection_table' object or a data frame with columns for sound file name (sound.files), selection number (selec), and start and end time of signal (start and end). It should contain the selections that will be used for detection optimization.

Y

An object of class 'autodetec.output' (generated by auto_detec) in which to optimize detections. Must refer to the same sound files as in 'X'. Optional.

threshold

A numeric vector of length 1 specifying the amplitude threshold for detecting signals (in %). Several values can be supplied for optimization.

power

A numeric vector of length 1 indicating a power factor applied to the amplitude envelope. Increasing power will reduce low amplitude modulations and increase high amplitude modulations, in order to reduce background noise. Default is 1 (no change). Several values can be supplied for optimization.

wl

A numeric vector of length 1 specifying the window used internally by ffilter for bandpass filtering (so only applied when 'bp' is supplied). Default is 512.

ssmooth

A numeric vector of length 1 to smooth the amplitude envelope with a sum smooth function. Default is 0 (no smoothing). Several values can be supplied for optimization.

hold.time

Numeric vector of length 1. Specifies the time range at which selections will be merged (i.e. if 2 selections are separated by less than the specified hold.time they will be merged in to a single selection). Default is 0. Several values can be supplied for optimization.

mindur

Numeric vector of length 1 giving the shortest duration (in seconds) of the signals to be detected. It removes signals below that threshold. Several values can be supplied for optimization.

maxdur

Numeric vector of length 1 giving the longest duration (in seconds) of the signals to be detected. It removes signals above that threshold. Several values can be supplied for optimization.

parallel

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

by.sound.file

Logical to control if diagnostics are calculated for each sound file independently (TRUE) or for all sound files combined (FALSE, default).

bp

Numeric vector of length 2 giving the lower and upper limits of a frequency bandpass filter (in kHz). Default is NULL.

path

Character string containing the directory path where the sound files are located. If NULL (default) then the current working directory is used. Only needed if 'Y' is not supplied.

Value

A data frame in which each row shows the result of a detection job with a particular combination of tuning parameters (including in the data frame). It also includes the following diagnostic metrics:

• true.positives: number of detections that correspond to signals referenced in 'X'. Matching is defined as some degree of overlap in time. In a perfect detection routine it should be equal to the number of rows in 'X'.

• false.positives: number of detections that don't match any of the signals referenced in 'X'. In a perfect detection routine it should be 0.

• split.positives: number of signals referenced in 'X' that were overlapped by more than 1 detection (i.e. detections that were split). In a perfect detection routine it should be 0.

• mean.duration.true.positives: mean duration of true positives (in s).

• mean.duration.false.positives: mean duration of false positives (in s).

• proportional.time.true.positives: ratio of total duration of true positives to the total duration of signals referenced in 'X'. In a perfect detection routine it should be 1.

• sensitivity: Proportion of signals referenced in 'X' that were detected. In a perfect detection routine it should be 1.

• specificity: Proportion of detections that correspond to signals referenced in 'X' that were detected. In a perfect detection routine it should be 1.

Details

This function takes a selections data frame or 'selection_table' ('X') and the output of a auto_detec routine ('Y') and estimates the detection performance for different detection parameter combinations. This is done by comparing the position in time of the detection to those of the reference selections in 'X'. The function returns several diagnostic metrics to allow user to determine which parameter values provide a detection that more closely matches the selections in 'X'. Those parameters can be later used for performing a more efficient detection using auto_detec.

References

Araya-Salas, M., & Smith-Vidaurre, G. (2017). warbleR: An R package to streamline analysis of animal acoustic signals. Methods in Ecology and Evolution, 8(2), 184-191.

Examples

# NOT RUN {
{
# Save to temporary working directory
data(list = c("Phae.long1", "Phae.long2", "Phae.long3", "Phae.long4", "selec.table"))
writeWave(Phae.long1, file.path(tempdir(), "Phae.long1.wav"))
writeWave(Phae.long2, file.path(tempdir(), "Phae.long2.wav"))
writeWave(Phae.long3, file.path(tempdir(), "Phae.long3.wav"))
writeWave(Phae.long4, file.path(tempdir(), "Phae.long4.wav"))

# try optimization with 2 tresholds
optimize_auto_detec(X = selec.table, threshold = c(10, 15), path = tempdir())

# this time by each sound file and 3 thresholds
optimize_auto_detec(X = selec.table, threshold = c(5, 10, 15), by.sound.file = TRUE, 
path = tempdir())

# run auto_detec with output list
ad <- auto_detec(output = "list", thinning = 1 / 10, ssmooth = 300, path = tempdir())
optimize_auto_detec(X = selec.table, Y = ad, threshold = c(5, 10, 15), path = tempdir())
}

# }