R/freq_range_detec.R

In warbleR: Streamline Bioacoustic Analysis

#' Detect frequency range on wave objects
#'
#' \code{freq_range_detec} detects the frequency range of acoustic signals on wave objects.
#' @usage freq_range_detec(wave, wl = 512, fsmooth = 0.1, threshold = 10,
#' dB.threshold = NULL, wn = "hanning", flim = NULL, bp = NULL,
#' fast.spec = FALSE, ovlp = 50, pal = reverse.gray.colors.2,
#'  widths = c(2, 1), main = NULL, plot = TRUE, all.detec = FALSE)
#' @param wave A 'wave' object produced by  \code{\link[tuneR]{readWave}} or similar functions.
#' @param wl A numeric vector of length 1 specifying the window length of the spectrogram, default
#'   is 512. This is used for calculating the frequency spectrum (using \code{\link[seewave]{meanspec}})
#'   and producing the spectrogram (using \code{\link[seewave]{spectro}}, if \code{plot = TRUE}).
#' @param fsmooth A numeric vector of length 1 to smooth the frequency spectrum with a mean
#'  sliding window in kHz. This help to average amplitude "hills" to minimize the effect of
#'  amplitude modulation. Default is 0.1.
#' @param threshold Amplitude threshold (\%) for frequency range detection. The frequency range (not the cumulative amplitude) is represented as percentage (100\% = highest amplitude). Default is 10. Ignored if 'dB.threshold' is supplied.
#' @param dB.threshold Amplitude threshold for frequency range detection (in dB). The
#' value indicates the decrease in dB in relation to the highest amplitude (e.g.
#' the peak frequency) in which range will be detected. For instance a
#' \code{dB.threshold = 20} means that the amplitude threshold would be 20 dB below
#' the highest amplitude. If provided 'threshold' is ignored. Default is \code{NULL}.
#' Note that the power spectrum is normalized when using a dB scale, so it looks different than the one produced when no dB scale is used (e.g. when using 'threshold' argument).
#' @param wn Character vector of length 1 specifying window name. Default is
#'   "hanning". See function \code{\link[seewave]{ftwindow}} for more options. This is used for calculating the frequency spectrum (using \code{\link[seewave]{meanspec}}) and producing the spectrogram (using \code{\link[seewave]{spectro}}, if \code{plot = TRUE}).
#' @param flim A numeric vector of length 2 for the frequency limit of
#'   the spectrogram (in kHz), as in \code{\link[seewave]{spectro}}. Default is \code{NULL}.
#' @param bp A numeric vector of length 2 for the lower and upper limits of a
#'   frequency bandpass filter (in kHz) or "frange" to indicate that values in 'bottom.freq'
#'   and 'top.freq' columns will be used as bandpass limits. Default is \code{NULL}.
#' @param fast.spec Logical. If \code{TRUE} then image function is used internally to create spectrograms, which substantially
#' increases performance (much faster), although some options become unavailable, as collevels, and sc (amplitude scale).
#' This option is indicated for signals with high background noise levels. Palette colors \code{\link[monitoR:specCols]{gray.1}}, \code{\link[monitoR:specCols]{gray.2}},
#' \code{\link[monitoR:specCols]{gray.3}}, \code{\link[monitoR:specCols]{topo.1}} and \code{\link[monitoR:specCols]{rainbow.1}} (which should be imported from the package monitoR) seem
#' to work better with 'fast.spec' spectrograms. Palette colors \code{\link[monitoR:specCols]{gray.1}}, \code{\link[monitoR:specCols]{gray.2}},
#' \code{\link[monitoR:specCols]{gray.3}} offer
#' decreasing darkness levels.
#' @param pal Color palette function for spectrogram. Default is reverse.gray.colors.2. See
#' \code{\link[seewave]{spectro}} for more palettes. Palettes as \code{\link[monitoR:specCols]{gray.2}} may work better when \code{fast.spec = TRUE}.
#' @param ovlp Numeric vector of length 1 specifying \% of overlap between two
#'   consecutive windows, as in \code{\link[seewave]{spectro}}. Default is 50. This is used for calculating the frequency spectrum (using \code{\link[seewave]{meanspec}}) and producing the spectrogram (using \code{\link[seewave]{spectro}}, if \code{plot = TRUE}).
#' @param widths Numeric vector of length 2 to control the relative widths of the spectro (first element) and spectrum (second element).
#' @param main  Character vector of length 1 specifying the plot title. Default is \code{NULL}.
#' @param plot Logical. Controls whether an image file is produced for each selection (in the
#' working directory). Default is \code{TRUE}.
#' @param all.detec Logical. If \code{TRUE} returns the start and end of all detected amplitude
#' "hills". Otherwise only the range is returned. Default is \code{FALSE}.
#' @return A data frame with 2 columns for low and high frequency values. A plot is produced (in the graphic device) if \code{plot = TRUE} (see details).
#' @export
#' @name freq_range_detec
#' @details This functions aims to automatize the detection of frequency ranges. The frequency range is calculated as follows:
#' \itemize{
#'  \item bottom.freq = the start frequency of the amplitude 'hill' containing the highest amplitude at the given threshold.
#'  \item top.freq = the end frequency of the amplitude 'hill' containing the highest amplitude at the given threshold.
#'   }
#'   If \code{plot = TRUE} a graph including a spectrogram and a frequency spectrum is
#'   produced in the graphic device. The graph would include gray areas in the frequency ranges excluded by the bandpass ('bp' argument), dotted lines highlighting the detected range.
#' @seealso \code{\link{frange}}, \code{\link{autodetec}}
#' @examples
#' {
#'   data(tico)
#'   freq_range_detec(
#'     wave = tico, wl = 512, fsmooth = 0.01, threshold = 1, bp = c(2, 8),
#'     widths = c(4, 2)
#'   )
#'
#'   data(sheep)
#'   freq_range_detec(
#'     wave = sheep, wl = 512, fsmooth = 0.2, threshold = 50, bp = c(0.3, 1),
#'     flim = c(0, 1.5), pal = reverse.heat.colors, main = "sheep"
#'   )
#' }
#'
#' @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 (\email{marcelo.araya@@ucr.ac.cr})
# last modification on apr-28-2017 (MAS)

freq_range_detec <- function(wave, wl = 512, fsmooth = 0.1, threshold = 10, dB.threshold = NULL, wn = "hanning", flim = NULL, bp = NULL, fast.spec = FALSE, ovlp = 50, pal = reverse.gray.colors.2, widths = c(2, 1), main = NULL, plot = TRUE, all.detec = FALSE) {
  # close screens
  on.exit(invisible(close.screen(all.screens = TRUE)))

  #### set arguments from options
  # get function arguments
  argms <- methods::formalArgs(freq_range_detec)

  # get warbleR options
  opt.argms <- if (!is.null(getOption("warbleR"))) getOption("warbleR") else SILLYNAME <- 0

  # remove options not as default in call and not in function arguments
  opt.argms <- opt.argms[!sapply(opt.argms, is.null) & names(opt.argms) %in% argms]

  # get arguments set in the call
  call.argms <- as.list(base::match.call())[-1]

  # remove arguments in options that are in call
  opt.argms <- opt.argms[!names(opt.argms) %in% names(call.argms)]

  # set options left
  if (length(opt.argms) > 0) {
    for (q in seq_len(length(opt.argms))) {
      assign(names(opt.argms)[q], opt.argms[[q]])
    }
  }

  frng <- frd_wrblr_int(wave = wave, wl = wl, fsmooth = fsmooth, threshold = threshold, dB.threshold = dB.threshold, wn = wn, bp = bp, ovlp = ovlp)

  if (plot) {
    frd_plot_wrblr_int(wave = wave, detections = frng, wl = wl, wn = wn, flim = flim, bp = bp, fast.spec = fast.spec, ovlp = ovlp, pal = pal, widths = widths, main = main, all.detec = all.detec)
  }

  # return low and high freq
  if (all.detec) {
    return(frng$detections)
  } else {
    return(frng$frange)
  }
}


##############################################################################################################
#' alternative name for \code{\link{freq_range_detec}}
#'
#' @keywords internal
#' @details see \code{\link{freq_range_detec}} for documentation. \code{\link{frange.detec}} will be deprecated in future versions.
#' @export

frange.detec <- freq_range_detec