rewrite of scrapenames for updated API

R/scrapenames.r

@@ -7,32 +7,61 @@
 #'   that this function is extremely buggy.
 #'
 #' @export
-#' @param url Defunct. Use the `text` input for URLs as well as text strings.
-#' @param file When using multipart/form-data as the content-type, a file may be
-#'   sent. This should be a path to your file on your machine.
-#' @param text A text (or URL pointing to a text) for name detection.
-#' @param engine (optional) (integer) Defunct. The API used no longer supports
-#'   this option.
-#' @param unique Defunct. See the `unique_names` option.
-#' @param unique_names (optional) (logical) If `TRUE` (the default), the output
-#'   returns unique names, instead of all name occurrences, without position
-#'   information of a name in the text.
-#' @param verbatim (optional) Defunct. The API used no longer supports this
-#'   option.
-#' @param detect_language (optional) Defunct. See the `language` option.
-#' @param language The language of the text. Language value is used for
+#' @param url (character) If text parameter is empty, and url is given, GNfinder will
+#'   process the URL and will find names in the content of its body.
+#' @param text (character) Contains the text which will be checked for scientific names. If
+#'   this parameter is not empty, the url parameter is ignored.
+#' @param format (character) Sets the output format. It can be set to: "csv" (the default),
+#'   "tsv", or "json".
+#' @param bytes_offset (logical) This changes how the position of a detected name in text
+#'   is calculated. Normally a name's start and end positions are given as the
+#'   number of UTF-8 characters from the beginning of the text. If bytesOffset
+#'   flag is true, the start and end offsets are recalculated in the number of
+#'   bytes.
+#' @param return_content (logical) If this is `TRUE`, the text used for the name
+#'   detection is returned back. This is especially useful if the input was not
+#'   a plain UTF-8 text and had to be prepared for name-finding. Then the
+#'   returned content can be used together with start and end fields of detected
+#'   name-strings to locate the strings in the text.
+#' @param unique_names (logical) If this is `TRUE`, the output returns a list of
+#'   unique names, instead of a list of all name occurrences. Unique list of
+#'   names does not provide position information of a name in the text.
+#' @param ambiguousNames (logical) If this is `TRUE`, strings which are simultaneously
+#'   scientific names and "normal" words are not filtered out from the results.
+#'   For example generic names like America, Cancer, Cafeteria will be returned
+#'   in the results.
+#' @param no_bayes (logical) If this is `TRUE`, only heuristic algorithms are used for
+#'   name detection.
+#' @param odds_details (logical) If true, the result will contain odds of all features
+#'   used for calculation of NaiveBayes odds. Odds describe probability of a
+#'   name to be 'real'. The higher the odds, the higher the probability that a
+#'   detected name is not a false positive. Odds are calculated by
+#'   multiplication of the odds of separate features. Odds details explain how
+#'   the final odds value is calculated.
+#' @param language (character) The language of the text. Language value is used for
 #'   calculation of Bayesian odds. If this parameter is not given, eng is used
 #'   by default. Currently only English and German languages are supported.
 #'   Valid values are: `eng`, `deu`, `detect`.
-#' @param all_data_sources (optional) Defunct. The API used no longer supports
-#'   this option.
-#' @param data_source_ids (optional) Defunct. See the `sources` option.
+#' @param words_around (integer) Allows to see the context surrounding a name-string. This
+#'   sets the number of words located immediately before or after a detected
+#'   name. These words are then returned in the output. Default is 0, maximum
+#'   value is 5.
+#' @param verification (character) When this `TRUE`, there is an additional
+#'   verification step for detected names. This step requires internet
+#'   connection and uses https://verifier.globalnames.org/api/v1 for
+#'   verification queries.
 #' @param sources Pipe separated list of data source ids to resolve found names
 #'   against. See list of Data Sources
 #'   http://resolver.globalnames.org/data_sources
-#' @param return_content (logical) return OCR'ed text. returns text string in
-#'   `x$meta$content` slot. Default: `FALSE`
 #' @param ... Further args passed to [crul::verb-GET]
+#' @param detect_language Defunct. See the `language` option.
+#' @param all_data_sources Defunct. The API used no longer supports this option.
+#' @param data_source_ids Defunct. See the `sources` option.
+#' @param file Defunct. If you feel this is important functionality submit an
+#'   issue at "https://github.com/ropensci/taxize"
+#' @param unique Defunct. See the `unique_names` option.
+#' @param engine Defunct. The API used no longer supports this option.
+#' @param verbatim Defunct. The API used no longer supports this option.
 #' @author Scott Chamberlain
 #' @return A list of length two, first is metadata, second is the data as a
 #'   data.frame.
@@ -74,25 +103,29 @@
 #' }
 scrapenames <- function(
     url = NULL,
-    file = NULL,
     text = NULL,
-    engine = NULL,
+    format = 'csv',
+    bytes_offset = FALSE,
+    return_content = FALSE,
+    unique_names = TRUE,
+    ambiguous_names = FALSE,
+    no_bayes = FALSE,
+    odds_details = FALSE,
+    language = 'detect',
+    words_around = 0,
+    verification = TRUE,
+    sources = NULL,
+    all_matches = FALSE,
+     ...,
+    file = NULL,
     unique = NULL,
-    unique_names = NULL,
-    verbatim = NULL,
+    engine = NULL,
     detect_language = NULL,
-    language = NULL,
-    all_data_sources = NULL,
     data_source_ids = NULL,
-    sources = NULL,
-    return_content = FALSE, 
-    ...
+    method = NULL
 ) {
 
   # Error if defunct parameters are used.
-  if (!is.null(url)) {
-    stop(call. = FALSE, 'The `url` option is defunct. Use the `text` option for URLs as well as text strings.')
-  }
   if (!is.null(unique)) {
     stop(call. = FALSE, 'The `unique` option is defunct. See the `unique_names` option. ')
   }
@@ -105,50 +138,42 @@ scrapenames <- function(
   if (!is.null(data_source_ids)) {
     stop(call. = FALSE, 'The `data_source_ids` option is defunct. See the `source` option. ')
   }
+  if (!is.null(method)) {
+    stop(call. = FALSE, 'This function can no longer submit files. If you feel this is important functionality submit an issue at "https://github.com/ropensci/taxize".')
+  }
 
-  method <- tc(list(url = url, file = file, text = text))
-  if (length(method) > 1) {
-    stop("Only one of url, file, or text can be used", call. = FALSE)
+  # Validate parameters
+  if (! format %in% c('csv', 'tsv', 'json')) {
+    stop(call. = FALSE, 'The `format` option must be "csv", "tsv", or "json". "', format, '" was the value given')
   }
-
+
+  # Make query
   base <- "http://gnrd.globalnames.org/api/v1/find"
-  if (!is.null(data_source_ids))
-    data_source_ids <- paste0(data_source_ids, collapse = "|")
-  args <- tc(list(
+  args <- list(
     text = text,
-    unique_names = unique_names,
-    verbatim = verbatim,
+    url = url,
+    format = format,
+    bytesOffset = bytes_offset,
+    returnContent = return_content,
+    uniqueNames = unique_names,
+    ambiguousNames = ambiguous_names,
+    noBayes = no_bayes,
+    oddsDetails = odds_details,
     language = language,
-    source = source,
-    return_content = as_l(return_content)
-  ))
+    wordsAround = words_around,
+    verification = verification,
+    sources = sources,
+    allMatches = all_matches
+  )
   cli <- crul::HttpClient$new(base, headers = tx_ual, opts = list(...))
-  if (names(method) == 'url') {
-    tt <- cli$get(query = args)
-    tt$raise_for_status()
-    out <- jsonlite::fromJSON(tt$parse("UTF-8"))
-    token_url <- out$token_url
-  } else {
-    if (names(method) == "text") {
-      tt <- cli$post(body = list(text = text), encode = "form",
-                 followlocation = 0)
-    } else {
-      tt <- cli$post(query = argsnull(args), encode = "multipart",
-                 body = list(file = crul::upload(file)), 
-                 followlocation = 0)
-    }
-    if (tt$status_code != 303) tt$raise_for_status()
-    token_url <- tt$response_headers$location
-    }
-
-  st <- 303
-  while (st == 303) {
-    dat <- crul::HttpClient$new(token_url, headers = tx_ual)$get()
-    dat$raise_for_status()
-    datout <- jsonlite::fromJSON(dat$parse("UTF-8"))
-    st <- datout$status
-  }
-  meta <- datout[!names(datout) %in% c("names")]
-  list(meta = meta, data = nmslwr(datout$names))
+  response <- cli$post(body = args, encode = "multipart")
+
+  # Parse and return results
+  switch (format,
+    csv = read.csv(text = response$parse("UTF-8")),
+    tsv = read.csv(text = response$parse("UTF-8"), sep = '\t'),
+    json = jsonlite::fromJSON(response$parse("UTF-8")),
+    other = stop("Invalid 'format' option.")
+  )
 }