Merge pull request #123 from sebpardo/make-defunct

Make functions defunct, update tests, docs, news, bump version, closes #112

DESCRIPTION

@@ -1,5 +1,5 @@
 Package: rebird
-Version: 1.3.9004
+Version: 1.3.9005
 Title: R Client for the eBird Database of Bird Observations
 Description: A programmatic client for the eBird database 
     (<https://ebird.org/home>), including functions for searching for bird 

NEWS.md

@@ -1,3 +1,13 @@
+rebird 1.3.9005
+===================
+
+- Added `ebirdchecklist()`, which lets you view individual checklists (thanks @RichardLitt and @Rafnuss, #108).
+- Made `ebirdregioncheck()`, `ebirdhotspot()`, `ebirdloc()` defunct. 
+- API tests now use `vcr`, which saves "cassettes" of the tests which can be played
+in CI when running tests during CI, instead of storing an API key and having to run
+tests remotely with every PR (thanks @slager).
+- Updated `rebird`'s internal taxonomy after 2023 taxonomic update.
+
 rebird 1.3.0
 ===================
 

R/ebirdfreq.R

@@ -96,8 +96,8 @@ ebirdfreq <- function(loctype, loc, startyear = 1900,
   url <- "http://ebird.org/ebird/barchartData"
   url_full <- modify_url(url, query = args)
   message(url_full)
-  stop(
-    "This function has been made temporarily defunct as you now need to be 
+  .Defunct(
+    msg = "This function has been made temporarily defunct as you now need to be 
     logged into the eBird website to download frequency data, but we cannot 
     authenticate via the API to do so. This function will be reinstated
     when the frequency data become available through the API. In the meantime, 

R/ebirdhotspot.R

@@ -1,72 +1,8 @@
-#' Recent observations at hotspots
-#'
-#' Returns the most recent sighting information reported in a given vector
-#' of hotspots.
-#' 
-#' @param locID (required) Vector containing code(s) for up to 10 regions of
-#'    interest; here, regions are the locIDs of hotspots. Values that are not
-#'    valid or are not hotspots are ignored.
-#' @param species Scientific name of the species of interest (not case
-#'    sensitive). Defaults to NULL, in which case sightings for all species
-#'    are returned.
-#'    See eBird taxonomy for more information:
-#'    http://ebird.org/content/ebird/about/ebird-taxonomy
-#' @param back Number of days back to look for observations (between
-#'    1 and 30, defaults to 14).
-#' @param max Maximum number of result rows to return in this request
-#'    (between 1 and 10000, defaults to all)
-#' @param locale Language/locale of response (when translations are available).
-#'    See http://java.sun.com/javase/6/docs/api/java/util/Locale.html
-#'    (defaults to en_US)
-#' @param provisional Should flagged records that have not been reviewed
-#'    be included? (defaults to FALSE)
-#' @param sleep Time (in seconds) before function sends API call (defaults to
-#'    zero.  Set to higher number if you are using this function in a loop with
-#'    many API calls).
-#' @param key eBird API key. You can obtain one from https://ebird.org/api/keygen.
-#'    We strongly recommend storing it in your \code{.Renviron} file as an 
-#'    environment variable called \code{EBIRD_KEY}.
-#' @param ... Curl options passed on to \code{\link[httr]{GET}}
-#' @return A data.frame containing the collected information:
-#' @return "comName": species common name
-#' @return "howMany": number of individuals observed, NA if only presence was noted
-#' @return "lat": latitude of the location
-#' @return "lng": longitude of the location
-#' @return "locID": unique identifier for the location
-#' @return "locName": location name
-#' @return "locationPrivate": TRUE if location is not a birding hotspot
-#' @return "obsDt": observation date formatted according to ISO 8601
-#'    (e.g. 'YYYY-MM-DD', or 'YYYY-MM-DD hh:mm'). Hours and minutes are excluded
-#'    if the observer did not report an observation time.
-#' @return "obsReviewed": TRUE if observation has been reviewed, FALSE otherwise
-#' @return "obsValid": TRUE if observation has been deemed valid by either the
-#'    automatic filters or a regional viewer, FALSE otherwise
-#' @return "sciName" species' scientific name
+#' This function is defunct.
 #' @export
-#' @examples \dontrun{
-#' ebirdhotspot(locID=c('L99381','L99382'), species='larus delawarensis')
-#' ebirdhotspot('L99381', max=10, provisional=TRUE)
-#' }
-#' @author Rafael Maia \email{rm72@@zips.uakron.edu}
-#' @references \url{http://ebird.org/}
+#' @rdname ebirdhotspot-defunct
+#' @keywords internal
 
-ebirdhotspot <-  function(locID, species=NULL, back = NULL, max = NULL, locale = NULL, 
-  provisional = FALSE, sleep = 0, key = NULL, ...) {
-  .Deprecated(new = "ebirdregion", 
-              msg = "Deprecated: 'ebirdhotspot' will be removed in the next version of rebird as it might not be supported in the new eBird API. Use 'ebirdregion' instead.")
-  if(length(locID) > 10) {
-    stop('Too many locations (maximum 10)')
-  }
-
-  Sys.sleep(sleep)
-
-  if(!is.null(back)) back <- round(back)
-
-  url <- paste0(ebase(), 'data/obs/', if(!is.null(species)) 'hotspot_spp/recent' else 'hotspot/recent')
-  args <- ebird_compact(list(fmt='json', sci=species, back=back, maxResults=max, locale=locale))
-  locs <- as.list(locID)
-  names(locs) <- rep("r", length(locID))
-  args <- c(args,locs)
-  if(provisional) args$includeProvisional <- 'true'  
-  ebird_GET(url, args, key = key, ...)
-}
+ebirdhotspot <-  function(...) { # nocov start
+  .Defunct(new = "ebirdregion")
+} # nocov end

R/ebirdloc.R

@@ -1,92 +1,8 @@
-#' Recent observations at a locality
-#' 
-#' Returns the most recent sighting information reported in a given vector 
-#' of locations (including non-hotspots).
-#' 
-#' @param locID (required) Vector containing code(s) for up to 10 regions of interest; 
-#' here, values that are not hotspots are returned. Values that are not valid are ignored. 
-#' @param species Scientific name of the species of interest (not case 
-#' sensitive). Defaults to NULL, in which case sightings for all species are returned.
-#' See eBird taxonomy for more information: 
-#' http://ebird.org/content/ebird/about/ebird-taxonomy
-#' @param back Number of days back to look for observations (between
-#'    1 and 30, defaults to 14).
-#' @param max Maximum number of result rows to return in this request
-#'    (between 1 and 10000, defaults to all)
-#' @param locale Language/locale of response (when translations are available).
-#'    See http://java.sun.com/javase/6/docs/api/java/util/Locale.html 
-#'    (defaults to en_US)
-#' @param provisional Should flagged records that have not been reviewed 
-#'    be included? (defaults to FALSE)
-#' @param simple Logical. Whether to return a simple (TRUE, default) or detailed
-#'    (FALSE) set of results fields.
-#' @param sleep Time (in seconds) before function sends API call (defaults to
-#'    zero.  Set to higher number if you are using this function in a loop with 
-#'    many API calls).
-#' @param key ebird API key. You can obtain one from https://ebird.org/api/keygen.
-#'    We strongly recommend storing it in your \code{.Renviron} file as an 
-#'    environment variable called \code{EBIRD_KEY}.
-#' @param ... Curl options passed on to \code{\link[httr]{GET}}
-#' @return A data.frame containing the collected information:
-#' @return "comName": species common name
-#' @return "howMany": number of individuals observed, NA if only presence was noted
-#' @return "lat": latitude of the location
-#' @return "lng": longitude of the location
-#' @return "locID": unique identifier for the location
-#' @return "locName": location name
-#' @return "locationPrivate": TRUE if location is not a birding hotspot
-#' @return "obsDt": observation date formatted according to ISO 8601 
-#'    (e.g. 'YYYY-MM-DD', or 'YYYY-MM-DD hh:mm'). Hours and minutes are excluded 
-#'    if the observer did not report an observation time. 
-#' @return "obsReviewed": TRUE if observation has been reviewed, FALSE otherwise
-#' @return "obsValid": TRUE if observation has been deemed valid by either the 
-#'    automatic filters or a regional viewer, FALSE otherwise
-#' @return "sciName" species' scientific name
-#' @return "subnational2Code": county code (returned if simple=FALSE)
-#' @return "subnational2Name": county name (returned if simple=FALSE)
-#' @return "subnational1Code": state/province ISO code (returned if simple=FALSE)
-#' @return "subnational1Name": state/province name (returned if simple=FALSE)
-#' @return "countryCode": country ISO code (returned if simple=FALSE)
-#' @return "countryName": country name (returned if simple=FALSE)
-#' @return "userDisplayName": first and last name of the observer (returned if simple=FALSE) 
-#' @return "firstName": observer's first name (returned if simple=FALSE)
-#' @return "lastName": observer's last name (returned if simple=FALSE)
-#' @return "subID": submission ID (returned if simple=FALSE)
-#' @return "obsID": observation ID (returned if simple=FALSE)
-#' @return "checklistID": checklist ID (returned if simple=FALSE)
-#' @return "presenceNoted": 'true' if user marked presence but did not count the
-#'   number of birds. 'false' otherwise (returned if simple=FALSE)
+#' This function is defunct.
 #' @export
-#' @examples \dontrun{
-#' ebirdloc(locID = c('L99381','L99382'))
-#' ebirdloc('L99381', 'Branta canadensis', provisional=TRUE)
-#' }
-#' @author Rafael Maia \email{rm72@@zips.uakron.edu}
-#' @references \url{http://ebird.org/}
+#' @rdname ebirdloc-defunct
+#' @keywords internal
 
-ebirdloc <-  function(locID, species=NULL, back = NULL, max = NULL, locale = NULL, 
-  provisional = FALSE, simple = TRUE, sleep = 0, key = NULL, ...) { # nocov start
-  .Deprecated(new = "ebirdregion", 
-              msg = "Deprecated: 'ebirdloc' will be removed in the next version of rebird as it might not be supported in the new eBird API. Use 'ebirdregion' instead.")
-  if (length(locID) > 10) {
-    stop('Too many locations (max. 10)', call. = FALSE)
-  }
-
-  Sys.sleep(sleep)
-  url <- paste0(ebase(), 'data/obs/', if(!is.null(species)) 'loc_spp/recent' else 'loc/recent')
-
-  if(!is.null(back)) {
-    back <- round(back) 
-  }
-
-  locID <- if(!is.null(locID)) locID <- paste0(locID, collapse = ",")
-  args <- ebird_compact(list(
-    fmt='json', sci=species,
-    r=locID, back=back, maxResults=max,
-    locale=locale
-  ))
-  if (provisional) args$includeProvisional <- 'true'
-  if (!simple) args$detail <- 'full'
-
-  ebird_GET(url, args, key = key, ...)
+ebirdloc <-  function(...) { # nocov start
+  .Defunct(new = "ebirdregion")
 } # nocov end

R/ebirdregioncheck.R

@@ -1,33 +1,8 @@
-#' Check if a region type is valid
-#'
-#' @param loc The location code to be checked. 
-#' @param key ebird API key. You can obtain one from https://ebird.org/api/keygen.
-#'    We strongly recommend storing it in your \code{.Renviron} file as an 
-#'    environment variable called \code{EBIRD_KEY}.
-#' @param ... Curl options passed on to \code{\link[httr]{GET}} 
-#'
-#' @return Logical.
+#' This function is defunct.
 #' @export
-#' 
-#' @examples \dontrun{
-#' ebirdregioncheck("US")
-#' ebirdregioncheck("CA-BC")
-#' ebirdregioncheck("CA-BC-GV")
-#' }
-#' @author Sebastian Pardo \email{sebpardo@@gmail.com},
-#'    Andy Teucher \email{andy.teucher@@gmail.com}
-#' @references \url{http://ebird.org/}
+#' @rdname ebirdregioncheck-defunct
+#' @keywords internal
 
-ebirdregioncheck <- function(loc, key = NULL, ...) { # nocov start
-  .Deprecated(new = "ebirdregioninfo", 
-              msg = "Deprecated: 'ebirdregioncheck' will be removed in the next version of rebird. Use 'ebirdregioninfo' instead.")
-  if (length(loc) > 1) {
-    stop("More than one location specified")
-  }
-  out <- try(ebirdregioninfo(loc, key = key, ...), silent = TRUE)
-  if ("try-error" %in% class(out) && 
-      !grepl("No region with code", out) &&   # To avoid error when using "HTTP 404" as location
-      grepl("HTTP [403|400]", out)) stop(out) # HTTP error codes that should 
-                                              # throw errors rather than return false
-  "tbl_df" %in% class(out)
+ebirdregioncheck <- function(...) { # nocov start
+  .Defunct(new = "ebirdregioninfo")
 } # nocov end

R/rebird-defunct.R

@@ -0,0 +1,10 @@
+#' Defunct functions in rebird
+#' 
+#' \itemize{
+#'  \item \code{\link{ebirdregioncheck}}: Use 'ebirdregioninfo' instead.
+#'  \item \code{\link{ebirdloc}}: Use 'ebirdregion' instead.
+#'  \item \code{\link{ebirdhotspot}}: Use 'ebirdregion' instead.
+#' }
+#' 
+#' @name rebird-defunct
+NULL