R/create_keywordSet.R

In CAPLTER/capeml: CAP LTER package for generating EML

#' @title create_keywordSet
#'
#' @description create_keywordSet generates a list of keywords and attributes
#'   that is suitable for passing to the keywordSet parameter of a eml$dataset
#'
#' @details A keywordSet entity is created from a single data file (.csv) with
#'   the fields: thesaurus, keyword, and type where type is an intended (but
#'   optional) attribute for the keyword.
#'
#' @param keywordsFile The quoted path and name of the keywords file.
#'
#' @import EML
#' @importFrom purrr map map2
#' @importFrom dplyr filter
#' @importFrom readr read_csv
#'
#' @return list of keywords and attributes that is suitable for passing to the
#'   keywordSet parameter of a eml$dataset
#'
#' @examples
#'
#' # After first generating a keyword template csv with write_keywords(), a
#' # EML::eml$keywordSet() entity can be generated from the data provided in the
#' # template csv:
#'
#' # keywords <- create_keywordSet('keywords.csv')
#'
#' # The workflow harvests keyword metadata from the keyword template generated by
#' # write_keywords() (i.e., keywords.csv) with the columns: thesaurus, keyword,
#' # and type, where type is an optional attribute that will be associated with
#' # the keyword EML/XML element.
#'
#' # The EML::eml$keywordSet() entity (`keywords` in this example) can then be
#' # added to a EML::eml$dataset() entity:
#'
#' # dataset <- EML::eml$dataset(keywordSet = keywords)
#'
#' @export
#'
create_keywordSet <- function(keywordsFile) {

  keywordsFile <- suppressMessages(readr::read_csv(keywordsFile))

  keywordSet <- purrr::map(unique(keywordsFile[['thesaurus']]), create_keywordList, keywordsFile = keywordsFile)

  return(keywordSet)

}

# create keyword function: helper function in the create_keywordSet workflow.
# Generates a EML keyword with or without an attribute
create_keyword <- function(datasetKeyword, keywordAttribute = NA) {

  # require function input: keyword
  if (missing(datasetKeyword)) { stop("keyword required")}

  # generate keyword sans attribute
  if (is.na(keywordAttribute) || keywordAttribute == '') {

    emlKeyword <- datasetKeyword

  } else {

    # generate keyword with attribute
    emlKeyword <- EML::eml$keyword(keywordType = keywordAttribute)
    emlKeyword$keyword <- datasetKeyword

  }

  return(emlKeyword)

}

# create keyword list function: helper function in the create_keywordSet
# workflow. Generates a list of keywords for a given thesaurus
create_keywordList <- function(category, keywordsFile) {

  thesaurusSubset <- keywordsFile %>%
    filter(thesaurus == category)

  keywordSubset <- purrr::map2(.x = thesaurusSubset$keyword, .y = thesaurusSubset$type, .f = create_keyword)

  emlKeywordList <- list(
    keyword          = keywordSubset,
    keywordThesaurus = category
  )

  return(emlKeywordList)

}