R/finbif_metadata.R

In finbif: Interface for the 'Finnish Biodiversity Information Facility' API

#' FinBIF metadata
#'
#' Display metadata from the FinBIF database.
#'
#' @aliases fb_metadata
#'
#' @param which Character. Which category of metadata to display. If
#'   unspecified, function returns the categories of metadata available.
#' @param locale Character. One of the supported two-letter ISO 639-1 language
#'   codes. Current supported languages are English, Finnish and Swedish. For
#'   data where more than one language is available the language denoted by
#'   `locale` will be preferred while falling back to the other languages in the
#'   order indicated above.
#' @param cache Logical or Integer. If `TRUE` or a number greater than zero,
#'   then data-caching will be used. If not logical then cache will be
#'   invalidated after the number of hours indicated by the argument.
#'
#' @return A data.frame.
#' @examples \dontrun{
#'
#' finbif_metadata("red_list")
#'
#' }
#' @export

finbif_metadata <- function(
  which,
  locale = getOption("finbif_locale"),
  cache = getOption("finbif_use_cache_metadata")
) {

  metadata_name <- c(
    "regulatory_status",
    "red_list",
    "country",
    "region",
    "bio_province",
    "municipality",
    "bird_assoc_area",
    "finnish_occurrence_status",
    "habitat_type",
    "habitat_qualifier",
    "life_stage",
    "record_basis",
    "restriction_level",
    "restriction_reason",
    "sex_category",
    "source",
    "taxon_rank"
  )

  data <- data.frame(metadata_name)

  if (!missing(which)) {

    if (!which %in% metadata_name) {

      stop(which, " not found in FinBIF metadata.", call. = FALSE)

    }

    obj <- list(cache = cache)

    obj[["which"]] <- switch(
      which,
      red_list = "red_list_status",
      sex_category = "sex",
      habitat_type = "primary_habitat",
      habitat_qualifier = "primary_habitat",
      which
    )

    data <- sysdata(obj)

    data <- switch(
      which,
      habitat_type = data[["habitat_types"]],
      habitat_qualifier = data[["specific_habitat_types"]],
      data
    )

    col_names <- "name"

    name <- paste0("name_", locale)

    if (!name %in% names(data)) {

      name <- "name_en"

      locale <- "en"

    }

    cols <- name

    description <- paste0("description_", locale)

    if (description %in% names(data)) {

      cols <- c(cols, description)

      col_names <- c(col_names, "description")

    }

    if ("code" %in% names(data)) {

      cols <- c("code", cols)

      col_names <- c("code", col_names)

    }

    ind <- order(data[[name]])

    data <- data[ind, cols, drop = FALSE]

    colnames(data) <- col_names

    class(data) <- c("finbif_metadata_df", "data.frame")

  }

  data

}