#723 standardize param names: done updating search fxns and get_* fxns

updated docs of these functions and fixed their tests started a new man file taxize-params with informaiton on standardized parameters
ropensci · May 21, 2020 · f4b0ad1 · f4b0ad1
1 parent 0d59526
commit f4b0ad1
Show file tree

Hide file tree

Showing 59 changed files with 934 additions and 712 deletions.
diff --git a/R/bold_search.R b/R/bold_search.R
@@ -1,7 +1,7 @@
 #' Search Barcode of Life for taxonomic IDs
 #'
 #' @export
-#' @param name (character) One or more scientific names.
+#' @param sci (character) One or more scientific names.
 #' @param id (integer) One or more BOLD taxonomic identifiers.
 #' @param fuzzy (logical) Whether to use fuzzy search or not (default: `FALSE`).
 #' Only used if `name` passed.
@@ -13,9 +13,10 @@
 #' passed.
 #' @param response (logical) Note that response is the object that returns from the
 #' curl call, useful for debugging, and getting detailed info on the API call.
+#' @param name Deprecated, see `sci`
 #' @param ... named curl options passed on to [crul::verb-GET]
-#' @details You must provide one of name or id to this function. The other
-#' parameters are optional. Note that when passing in `name`, `fuzzy` can be used
+#' @details You must provide one of `sci` or `id` to this function. The other
+#' parameters are optional. Note that when passing in `sci`, `fuzzy` can be used
 #' as well, while if `id` is passed, then `fuzzy` is ignored, and `dataTypes`
 #' `includeTree` can be used.
 #'
@@ -41,18 +42,18 @@
 #' @return A list of data.frame's.
 #' @examples \dontrun{
 #' # A basic example
-#' bold_search(name="Apis")
-#' bold_search(name="Agapostemon")
-#' bold_search(name="Poa")
+#' bold_search(sci="Apis")
+#' bold_search(sci="Agapostemon")
+#' bold_search(sci="Poa")
 #'
 #' # Fuzzy search
-#' head(bold_search(name="Po", fuzzy=TRUE))
-#' head(bold_search(name="Aga", fuzzy=TRUE))
+#' head(bold_search(sci="Po", fuzzy=TRUE))
+#' head(bold_search(sci="Aga", fuzzy=TRUE))
 #'
 #' # Many names
-#' bold_search(name=c("Apis","Puma concolor"))
+#' bold_search(sci=c("Apis","Puma concolor"))
 #' nms <- names_list('species')
-#' bold_search(name=nms)
+#' bold_search(sci=nms)
 #'
 #' # Searching by ID - dataTypes can be used, and includeTree can be used
 #' bold_search(id=88899)
@@ -61,14 +62,15 @@
 #' bold_search(id=88899, dataTypes="basic")
 #' bold_search(id=88899, includeTree=TRUE)
 #' }
+bold_search <- function(sci = NULL, id = NULL, fuzzy = FALSE,
+  dataTypes = 'basic', includeTree=FALSE, response=FALSE, name = NULL, ...) {
 
-bold_search <- function(name = NULL, id = NULL, fuzzy = FALSE,
-  dataTypes = 'basic', includeTree=FALSE, response=FALSE, ...) {
-
-  stopifnot(!is.null(name) | !is.null(id))
-  type <- if (is.null(name)) "id" else "name"
+  pchk(name, "sci")
+  if (!is.null(name)) sci <- name
+  stopifnot(!is.null(sci) | !is.null(id))
+  type <- if (is.null(sci)) "id" else "sci"
   tmp <- switch(type,
-         name = bold_tax_name(name = name, fuzzy = fuzzy, response = response, ...),
+         sci = bold_tax_name(name = sci, fuzzy = fuzzy, response = response, ...),
          id = bold_tax_id(id = id, dataTypes = dataTypes, includeTree = includeTree,
                           response = response, ...)
   )

diff --git a/R/eol_search.R b/R/eol_search.R
@@ -1,7 +1,7 @@
 #' Search for terms in EOL database.
 #'
 #' @export
-#' @param terms search terms (character)
+#' @param sci (character) scientific name
 #' @param page A maximum of 30 results are returned per page. This parameter
 #' allows you to fetch more pages of results if there are more than
 #' 30 matches (Default 1)
@@ -15,6 +15,7 @@
 #' and that matching page will be used as the taxonomic group against which
 #' to filter search results
 #' @param cache_ttl The number of seconds you wish to have the response cached.
+#' @param terms Deprecated, see `sci`
 #' @param ... Curl options passed on to [crul::HttpClient]
 #' @details It's possible to return JSON or XML with the EOL API. However,
 #' 		this function only returns JSON for now.
@@ -30,16 +31,17 @@
 #' in case some may find it useful
 #'
 #' @examples \dontrun{
-#' eol_search(terms='Homo')
-#' eol_search(terms='Salix', verbose = TRUE)
-#' eol_search(terms='Ursus americanus')
+#' eol_search(sci='Homo')
+#' eol_search(sci='Salix', verbose = TRUE)
+#' eol_search(sci='Ursus americanus')
 #' eol_search('Pinus contorta')
 #' }
 
-eol_search <- function(terms, page=1, exact=NULL, filter_tid=NULL,
-  filter_heid=NULL, filter_by_string=NULL, cache_ttl=NULL, ...) {
+eol_search <- function(sci, page=1, exact=NULL, filter_tid=NULL,
+  filter_heid=NULL, filter_by_string=NULL, cache_ttl=NULL, terms = NULL, ...) {
 
-	query <- gsub("\\s", "+", terms)
+  pchk(terms, "sci")
+	query <- gsub("\\s", "+", sci)
   args <- tc(list(q = query, page = page, exact = exact,
                   filter_by_taxon_concept_id = filter_tid,
                   filter_by_hierarchy_entry_id = filter_heid,

diff --git a/R/get_boldid.R b/R/get_boldid.R
@@ -2,7 +2,7 @@
 #'
 #' @importFrom bold bold_tax_name bold_tax_id
 #' @export
-#' @param searchterm character; A vector of scientific names. Or,
+#' @param sci character; A vector of scientific names. Or,
 #' a `taxon_state` object (see [taxon-state])
 #' @param fuzzy (logical) Whether to use fuzzy search or not (default: FALSE).
 #' @param dataTypes (character) Specifies the datatypes that will be returned.
@@ -28,6 +28,7 @@
 #' data itself for options. Optional. See `Filtering` below.
 #' @param check logical; Check if ID matches any existing on the DB, only used in
 #' [as.boldid()]
+#' @param searchterm Deprecated, see `sci`
 #' @template getreturn
 #'
 #' @section Filtering:
@@ -41,20 +42,20 @@
 #' @seealso [classification()]
 #'
 #' @examples \dontrun{
-#' get_boldid(searchterm = "Agapostemon")
-#' get_boldid(searchterm = "Chironomus riparius")
+#' get_boldid(sci = "Agapostemon")
+#' get_boldid(sci = "Chironomus riparius")
 #' get_boldid(c("Chironomus riparius","Quercus douglasii"))
 #' splist <- names_list('species')
 #' get_boldid(splist, messages=FALSE)
 #'
 #' # Fuzzy searching
-#' get_boldid(searchterm="Osmi", fuzzy=TRUE)
+#' get_boldid(sci="Osmi", fuzzy=TRUE)
 #'
 #' # Get back a subset
-#' get_boldid(searchterm="Osmi", fuzzy=TRUE, rows = 1)
-#' get_boldid(searchterm="Osmi", fuzzy=TRUE, rows = 1:10)
-#' get_boldid(searchterm=c("Osmi","Aga"), fuzzy=TRUE, rows = 1)
-#' get_boldid(searchterm=c("Osmi","Aga"), fuzzy=TRUE, rows = 1:3)
+#' get_boldid(sci="Osmi", fuzzy=TRUE, rows = 1)
+#' get_boldid(sci="Osmi", fuzzy=TRUE, rows = 1:10)
+#' get_boldid(sci=c("Osmi","Aga"), fuzzy=TRUE, rows = 1)
+#' get_boldid(sci=c("Osmi","Aga"), fuzzy=TRUE, rows = 1:3)
 #'
 #' # found
 #' get_boldid('Epicordulia princeps')
@@ -107,12 +108,12 @@
 #' get_boldid_(c("Osmi","Aga"), fuzzy=TRUE, rows = 1:3)
 #' }
 
-get_boldid <- function(searchterm, fuzzy = FALSE, dataTypes = 'basic',
+get_boldid <- function(sci, fuzzy = FALSE, dataTypes = 'basic',
                        includeTree = FALSE, ask = TRUE, messages = TRUE,
                        rows = NA, rank = NULL, division = NULL,
-                       parent = NULL, ...) {
+                       parent = NULL, searchterm = NULL, ...) {
 
-  assert(searchterm, c("character", "taxon_state"))
+  assert(sci, c("character", "taxon_state"))
   assert(ask, "logical")
   assert(messages, "logical")
   assert(fuzzy, "logical")
@@ -122,26 +123,27 @@ get_boldid <- function(searchterm, fuzzy = FALSE, dataTypes = 'basic',
   assert(division, "character")
   assert(parent, "character")
   assert_rows(rows)
+  pchk(searchterm, "sci")
 
-  if (inherits(searchterm, "character")) {
-    tstate <- taxon_state$new(class = "boldid", names = searchterm)
-    items <- searchterm
+  if (inherits(sci, "character")) {
+    tstate <- taxon_state$new(class = "boldid", names = sci)
+    items <- sci
   } else {
-    assert_state(searchterm, "boldid")
-    tstate <- searchterm
-    searchterm <- tstate$taxa_remaining()
-    items <- c(searchterm, tstate$taxa_completed())
+    assert_state(sci, "boldid")
+    tstate <- sci
+    sci <- tstate$taxa_remaining()
+    items <- c(sci, tstate$taxa_completed())
   }
 
   prog <- progressor$new(items = items, suppress = !messages)
   done <- tstate$get()
   for (i in seq_along(done)) prog$completed(names(done)[i], done[[i]]$att)
   prog$prog_start()
 
-  for (i in seq_along(searchterm)) {
+  for (i in seq_along(sci)) {
     direct <- FALSE
-    mssg(messages, "\nRetrieving data for taxon '", searchterm[i], "'\n")
-    bold_df <- bold_search(name = searchterm[i], fuzzy = fuzzy,
+    mssg(messages, "\nRetrieving data for taxon '", sci[i], "'\n")
+    bold_df <- bold_search(sci = sci[i], fuzzy = fuzzy,
                            dataTypes = dataTypes,
                            includeTree = includeTree, ...)
     mm <- NROW(bold_df) > 1
@@ -182,7 +184,7 @@ get_boldid <- function(searchterm, fuzzy = FALSE, dataTypes = 'basic',
         # check for direct match
         if (nrow(bold_df) > 1) {
           names(bold_df)[grep('taxon', names(bold_df))] <- "target"
-          di_rect <- match(tolower(bold_df$target), tolower(searchterm[i]))
+          di_rect <- match(tolower(bold_df$target), tolower(sci[i]))
           if (length(di_rect) == 1) {
             if (!all(is.na(di_rect))) {
               boldid <- bold_df$taxid[!is.na(di_rect)]
@@ -237,7 +239,7 @@ get_boldid <- function(searchterm, fuzzy = FALSE, dataTypes = 'basic',
               # prompt
               message("\n\n")
               print(bold_df)
-              message("\nMore than one TSN found for taxon '", searchterm[i], "'!\n
+              message("\nMore than one TSN found for taxon '", sci[i], "'!\n
             Enter rownumber of taxon (other inputs will return 'NA'):\n") # prompt
               take <- scan(n = 1, quiet = TRUE, what = 'raw')
 
@@ -259,7 +261,7 @@ get_boldid <- function(searchterm, fuzzy = FALSE, dataTypes = 'basic',
             if (length(boldid) == 1) {
               att <- "found"
             } else {
-              warning(sprintf(m_more_than_one_found, "boldid", searchterm[i]),
+              warning(sprintf(m_more_than_one_found, "boldid", sci[i]),
                 call. = FALSE)
               boldid <- NA_character_
               att <- m_na_ask_false
@@ -270,9 +272,9 @@ get_boldid <- function(searchterm, fuzzy = FALSE, dataTypes = 'basic',
     }
     res <- list(id = as.character(boldid), att = att, multiple = mm,
       direct = direct)
-    prog$completed(searchterm[i], att)
+    prog$completed(sci[i], att)
     prog$prog(att)
-    tstate$add(searchterm[i], res)
+    tstate$add(sci[i], res)
   }
   out <- tstate$get()
   ids <- structure(as.character(unlist(pluck(out, "id"))), class = "boldid",
@@ -347,19 +349,20 @@ check_boldid <- function(x){
 
 #' @export
 #' @rdname get_boldid
-get_boldid_ <- function(searchterm, messages = TRUE, fuzzy = FALSE,
-  dataTypes='basic', includeTree=FALSE, rows = NA, ...) {
+get_boldid_ <- function(sci, messages = TRUE, fuzzy = FALSE,
+  dataTypes='basic', includeTree=FALSE, rows = NA, searchterm = NULL, ...) {
 
-  stats::setNames(lapply(searchterm, get_boldid_help, messages = messages,
+  pchk(searchterm, "sci")
+  stats::setNames(lapply(sci, get_boldid_help, messages = messages,
     fuzzy = fuzzy, dataTypes=dataTypes, includeTree=includeTree,
-    rows = rows, ...), searchterm)
+    rows = rows, ...), sci)
 }
 
-get_boldid_help <- function(searchterm, messages, fuzzy, dataTypes,
+get_boldid_help <- function(sci, messages, fuzzy, dataTypes,
   includeTree, rows, ...){
 
-  mssg(messages, "\nRetrieving data for taxon '", searchterm, "'\n")
-  df <- bold_search(name = searchterm, fuzzy = fuzzy, dataTypes = dataTypes,
+  mssg(messages, "\nRetrieving data for taxon '", sci, "'\n")
+  df <- bold_search(name = sci, fuzzy = fuzzy, dataTypes = dataTypes,
     includeTree = includeTree)
   if(NROW(df) == 0) NULL else sub_rows(df, rows)
 }