R/lfdcs2raven.R

In hansenjohnson/lfdcs2raven: Review LFDCS Output in Raven Pro

#' lfdcs2raven
#'
#' A simple package for reviewing LFDCS output in Raven Pro
#'
#' @docType package
#' @name lfdcs2raven
NULL

#' Generate a Raven selection table from LFDCS autodetections
#'
#' @details
#' The Low-Frequency Detection and Classification System (\href{https://www.whoi.edu/cms/files/JASMAN12952889_85804.pdf}{LFDCS}) automatically detects
#' marine mammal vocalizations in large datasets. This script converts a csv file of
#' LFDCS autodetections (extracted from raw detector output using `export_autodetections`)
#' into a text file that can be imported into Raven Pro as a selection table.
#'
#' @param lfdcs_file The autodetections generated by \code{export_autodetections}
#' @param raven_file The desired name (.txt) of the Raven selection table
#' @param audio_start_time String giving the audio start time (YYYY-mm-dd HH:MM:SS)
#' @param lfdcs_start_time String giving the lfdcs start time (YYYY-mm-dd HH:MM:SS)
#' @param call_types A vector of desired call types
#' @param max_mdist A numeric value indicating the maximum Mahalanobis distance to export
#' @param t_buff The time buffer (in seconds) that is added to the start and end of each selection. This helps make the selection more visible in Raven.
#' @param f_buff The frequency buffer (in Hz) that is added to the top and bottom of each selection. This helps make the selection more visible in Raven.
#'
#' @examples
#' '\dontrun{
#' # export all autodetections
#' lfdcs_to_raven(
#'  lfdcs_file = 'lfdcs_autodetections.csv',
#'  raven_file = 'raven_selections.txt',
#'  audio_start_time = '2017-08-01 17:44:27',
#' )
#'
#' # export high quality right whale autodetections
#' lfdcs_to_raven(
#'  lfdcs_file = 'lfdcs_autodetections.csv',
#'  raven_file = 'raven_selections.txt',
#'  audio_start_time = '2017-08-01 17:44:27',
#'  call_types = c(5,6,7,8,9),
#'  max_mdist = 3
#' )
#'}
#'
#' @author Hansen Johnson (\email{hansen.johnson@@dal.ca})
#' @importFrom magrittr %>%
#'
#' @export
lfdcs_to_raven <- function(lfdcs_file,
                           raven_file = 'selections.txt',
                           audio_start_time,
                           lfdcs_start_time = '1970-01-01 00:00:00',
                           call_types = '',
                           max_mdist = '',
                           t_buff = 0.5,
                           f_buff = 25){

  # read csv header
  hd <- readLines(lfdcs_file, n = 100)

  # find last line of metadata
  ln <- grep(pattern = 'Mahalanobis distance', x = hd)

  # read in and format lfdcs autodetections
  message('Reading in autodetections...')
  lf <- readr::read_csv(lfdcs_file, skip = ln, col_types = readr::cols(),
                        col_names = c('call_type', 'start_time', 'end_time', 'duration', 'min_freq', 'max_freq', 'bandwidth','amplitude','mdist')) %>%
    dplyr::mutate(
      start_time = as.POSIXct(start_time-t_buff, origin = lfdcs_start_time, tz = 'UTC'),
      end_time = as.POSIXct(end_time+t_buff, origin = lfdcs_start_time, tz='UTC'),
      min_freq = round(min_freq - f_buff, 3),
      max_freq = round(max_freq + f_buff, 3)
    )

  # subset call types
  if(call_types[1]!=''){
    lf <- lf %>% dplyr::filter(call_type %in% call_types)
  }

  # subset mdist
  if(max_mdist!=''){
    lf <- lf %>% dplyr::filter(mdist <= max_mdist)
  }

  # check for data
  if(nrow(lf)==0){
    message("No autodetections meet the criteria :(")
    return(message("Try again with different call types or mahalanobis distance..."))
  }

  # format start time
  t0 <- as.POSIXct(audio_start_time, tz = 'UTC')

  # compute start / end times
  lf$start_time <- round(as.numeric(lf$start_time)-as.numeric(t0) - t_buff, 3)
  lf$end_time <- round(as.numeric(lf$end_time)-as.numeric(t0) + t_buff, 3)

  # trim start/end times to within the acoustic record
  lf$start_time[lf$start_time<0] <- 0
  lf$end_time[lf$end_time<0] <- 0

  # trim min/max frequencies to 0-1000 Hz
  lf$max_freq[lf$max_freq>1000]<-1000
  lf$min_freq[lf$min_freq>1000]<-1000
  lf$max_freq[lf$max_freq<0]<-0
  lf$min_freq[lf$min_freq<0]<-0

  # create raven table
  rv <- dplyr::tibble(
    Selection = seq(from=1,to=nrow(lf)),
    View = 'Spectrogram',
    Channel = 1,
    `Begin Time (s)` = lf$start_time,
    `End Time (s)` = lf$end_time,
    `Low Freq (Hz)` = lf$min_freq,
    `High Freq (Hz)` = lf$max_freq,
    call_type = lf$call_type,
    mdist = lf$mdist
  )

  # save output
  utils::write.table(rv, raven_file, sep = '\t',quote = FALSE, row.names = FALSE)
  message('Selection table saved as: ', raven_file)

}