R/getHLdata.R

In ices-tools-prod/icesDatras: DATRAS Trawl Survey Database Web Services

#' Get Length-Based Data
#'
#' Get length-based information such as measured length, individual counts,
#'   and sub-factors of sampled species.
#'
#' @param survey the survey acronym, e.g. NS-IBTS.
#' @param year the year of the survey, e.g. 2010.
#' @param quarter the quarter of the year the survey took place, i.e. 1, 2, 3 or 4.
#' @param species the valid aphia code of the species to download, if NULL all species are included
#'
#' @return A data frame.
#'
#' @seealso
#' \code{\link{getDATRAS}} supports querying many years and quarters in one function call.
#'
#' \code{\link{getHHdata}} and \code{\link{getCAdata}} get haul data and
#' age-based data.
#'
#' \code{\link{icesDatras-package}} gives an overview of the package.
#'
#'
#' @examples
#' \dontrun{
#' hldata <- getHLdata(survey = "BTS", year = 1993, quarter = 3, species = 105883)
#' str(hldata)
#' }
#' @export

getHLdata <- function(survey, year, quarter, species) {
  # check survey name
  if (!checkSurveyOK(survey)) {
    return(FALSE)
  }

  # check year
  if (!checkSurveyYearOK(survey, year, checksurvey = FALSE)) {
    return(FALSE)
  }

  # check quarter
  if (!checkSurveyYearQuarterOK(survey, year, quarter, checksurvey = FALSE, checkyear = FALSE)) {
    return(FALSE)
  }

  # read url and parse to data frame
  if (!is.null(species)) {
    url <-
      sprintf(
        "https://datras.ices.dk/WebServices/DATRASWebService.asmx/getHLdataSp?survey=%s&year=%i&quarter=%i&species=%i",
        survey, year, quarter, species
      )
  } else {
    url <-
      sprintf(
        "https://datras.ices.dk/WebServices/DATRASWebService.asmx/getHLdata?survey=%s&year=%i&quarter=%i",
        survey, year, quarter
      )
  }

  out <- readDatras(url)
  out <- parseDatras(out)

  out
}