auto_detec automatically detects the start and end of vocalizations in sound files based on amplitude, duration, and frequency range attributes.

auto_detec automatically detects the start and end of vocalizations in sound files based on amplitude, duration, and frequency range attributes.

Usage

auto_detec(X = NULL, wl = 512, threshold = 15, parallel = 1, power = 1,
   output = 'data.frame', thinning = 1, path = NULL, pb = TRUE, ssmooth = 0,
   bp = NULL, flist = NULL, hold.time = 0, mindur = NULL, maxdur = NULL, envt = NULL,
   msmooth = NULL, osci = NULL, xl = NULL, picsize = NULL, res = NULL, flim = NULL,
   ls = NULL, sxrow = NULL, rows = NULL,  redo = NULL, img = NULL, it = NULL,
   set = NULL, smadj = NULL, pal = NULL, fast.spec = 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). If provided the detection will be conducted only within the selections in 'X'. Alternatively, an 'autodetec.output' object can be input. These objects are also generated by this function when output = "list". If so the detection runs much faster as envelopes have been already calculated.
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.
threshold: A numeric vector of length 1 specifying the amplitude threshold for detecting signals (in %).
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).
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).
output: Character string indicating if the output should be a 'data.frame' with the detections (default) or a list (of class 'autodetec.output') containing both 1) the detections and 2) the amplitude envelopes (time vs amplitude) for each sound file. The list can be input into full_spectrograms to explore detections and associated amplitude envelopes.
thinning: Numeric vector of length 1 in the range 0~1 indicating the proportional reduction of the number of samples used to represent amplitude envelopes (i.e. the thinning of the envelopes). Usually amplitude envelopes have many more samples than those needed to accurately represent amplitude variation in time, which affects the size of the output (usually very large R objects / files). Default is 1 (no thinning). Higher sampling rates can afford higher size reduction (e.g. lower thinning values). Reduction is conducted by interpolation using approx. Note that thinning may decrease time precision, and the higher the thinning the less precise the time detection.
path: Character string containing the directory path where the sound files are located. If NULL (default) then the current working directory is used.
pb: Logical argument to control progress bar. Default is TRUE.
ssmooth: A numeric vector of length 1 to smooth the amplitude envelope with a sum smooth function. Default is 0. Note that smoothing is applied before thinning (see 'thinning' argument).
bp: Numeric vector of length 2 giving the lower and upper limits of a frequency bandpass filter (in kHz). Default is NULL.
flist: character vector or factor indicating the subset of files that will be analyzed. Ignored if X is provided.
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.
mindur: Numeric vector of length 1 giving the shortest duration (in seconds) of the signals to be detected. It removes signals below that threshold.
maxdur: Numeric vector of length 1 giving the longest duration (in seconds) of the signals to be detected. It removes signals above that threshold.
envt: DEPRECATED.
msmooth: DEPRECATED.
osci: DEPRECATED.
xl: DEPRECATED
picsize: DEPRECATED
res: DEPRECATED
flim: DEPRECATED
ls: DEPRECATED
sxrow: DEPRECATED
rows: DEPRECATED
redo: DEPRECATED.
img: DEPRECATED.
it: DEPRECATED.
set: DEPRECATED.
smadj: DEPRECATED.
pal: DEPRECATED.
fast.spec: DEPRECATED.

Value

A data frame containing the start and end of each signal by sound file and selection number. If 'output = "list"' then a list including 1) a detection data frame, 2) amplitude envelopes and 3) parameters will be return. An additional column 'org.selec' is added when 'X' is provided (so detection can be traced back to the selections in 'X').

Details

This function determines the start and end of signals in the sound file selections listed in the input data frame ('X'). Alternatively, if no data frame is provided, the function detects signals across each entire sound file. It can also create long spectrograms highlighting the start and of the detected signals for all sound files in the working directory (if img = TRUE). Sound files should be located in the working directory or the path to the sound files should be provided using the 'path' argument. The input data frame should have the following columns: c("sound.files","selec","start","end"). This function uses a modified version of the timer function from seewave package to detect signals. Note that warbleR function for signal detection will be deprecated in future warbleR versions. Look at the ohun package for automatic signal detection functions.

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.

Author

Marcelo Araya-Salas (marcelo.araya@ucr.ac.cr). Implements a modified version of the timer function from seewave.

Examples

{
  # Save to temporary working directory
  data(list = c("Phae.long1", "Phae.long2", "Phae.long3", "Phae.long4"))
  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"))

  ad <- auto_detec(
    threshold = 5, ssmooth = 300,
    bp = c(2, 9), wl = 300, path = tempdir()
  )
}
#> Warning: This function will be deprecated in future warbleR versions, please look at the ohun package for automatic signal detection functions (https://marce10.github.io/ohun/index.html)
#> Detecting signals in sound files:

`auto_detec` automatically detects the start and end of vocalizations in sound files based on amplitude, duration, and frequency range attributes.