get_acoustic_deployment_logs.R

#' Retrieve log files/diagnostic information for deployments of acoustic
#' receivers.
#'
#' This function retrieves log files and diagnostic information for deployments
#' of acoustic receivers from the ETN database. The returned data includes
#' deployment ID, receiver ID, station name, datetime, record type, and log data
#' in JSON format.
#'
#' @inheritParams get_acoustic_detections
#' @inheritParams get_acoustic_deployments
#' @inheritParams list_animal_ids
#'
#' @returns A tibble with receiver diagnostics data. The data is embedded in a
#'   `log_data` column that is JSON formatted.
#' @export
#'
#' @examples
#' get_acoustic_deployment_logs(deployment_id = 6028)
#'
#' get_acoustic_deployment_logs(deployment_id = c(53790, 1758), limit = TRUE)
get_acoustic_deployment_logs <- function(credentials = list(
                                username = Sys.getenv("ETN_USER"),
                                password = Sys.getenv("ETN_PWD")),
                              deployment_id,
                              limit = FALSE) {
  # Check if credentials object has right shape
  check_credentials(credentials)

  # Create connection object
  connection <- connect_to_etn(credentials$username, credentials$password)

  # Ensure the connection is closed when the function exits, even when it fails.
  withr::defer(
    if (DBI::dbIsValid(connection)) {
      DBI::dbDisconnect(connection)
    }
  )

  # Check connection
  check_connection(connection)

  # Check deployment_id
  if(missing(deployment_id)){
    rlang::abort(
      message = "Please provide at least one `deployment_id`",
      class = "etn_no_dep_id_supplied"
    )
  } else {
    # If the deployment ID is present:
    deployment_id <- check_value(
      deployment_id,
      list_deployment_ids(credentials),
      "deployment_id"
    )
    deployment_id_query <- glue::glue_sql(
      "deployment_fk IN ({deployment_id*})",
      .con = connection
    )
  }

  # Check limit
  assertthat::assert_that(is.logical(limit),
                          msg = "limit must be a logical: TRUE/FALSE.")
  if (limit) {
    limit_query <- glue::glue_sql("LIMIT 100", .con = connection)
  } else {
    limit_query <- glue::glue_sql("LIMIT ALL}", .con = connection)
  }

  # Build query
  query <-
    glue::glue_sql(
    "SELECT DISTINCT
      log.deployment_fk AS deployment_id,
      receiver.receiver AS receiver_id,
      dep.station_name AS station_name,
      log.datetime AS datetime,
      log.record_type,
      log.log_data
    FROM
      acoustic.receiver_logs_data AS log
      LEFT JOIN acoustic.deployments AS dep
        ON log.deployment_fk = dep.id_pk
      LEFT JOIN acoustic.receivers AS receiver
        ON dep.receiver_fk = receiver.id_pk
    WHERE
      {deployment_id_query}
    {limit_query}",
    .con = connection,
    .null = "NULL"
    )

  ## Query database
  deployment_logs <- DBI::dbGetQuery(connection, query)
  # Close connection
  DBI::dbDisconnect(connection)

  # Sort data
  deployment_logs <-
    deployment_logs |>
    dplyr::arrange(factor(
      .data$deployment_id, levels = list_deployment_ids(credentials)
    ))

  dplyr::as_tibble(deployment_logs)
}