Skip to content

Commit

Permalink
Make functions defunct, update tests, docs, news, bump version
Browse files Browse the repository at this point in the history
  • Loading branch information
sebpardo committed Mar 24, 2024
1 parent bb965ab commit eff8ff2
Show file tree
Hide file tree
Showing 21 changed files with 95 additions and 625 deletions.
2 changes: 1 addition & 1 deletion DESCRIPTION
Original file line number Diff line number Diff line change
@@ -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
Expand Down
10 changes: 10 additions & 0 deletions NEWS.md
Original file line number Diff line number Diff line change
@@ -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
===================

Expand Down
4 changes: 2 additions & 2 deletions R/ebirdfreq.R
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
76 changes: 6 additions & 70 deletions R/ebirdhotspot.R
Original file line number Diff line number Diff line change
@@ -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
94 changes: 5 additions & 89 deletions R/ebirdloc.R
Original file line number Diff line number Diff line change
@@ -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
35 changes: 5 additions & 30 deletions R/ebirdregioncheck.R
Original file line number Diff line number Diff line change
@@ -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
10 changes: 10 additions & 0 deletions R/rebird-defunct.R
Original file line number Diff line number Diff line change
@@ -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
12 changes: 0 additions & 12 deletions R/rebird-deprecated.R

This file was deleted.

12 changes: 12 additions & 0 deletions man/ebirdhotspot-defunct.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

96 changes: 0 additions & 96 deletions man/ebirdhotspot.Rd

This file was deleted.

12 changes: 12 additions & 0 deletions man/ebirdloc-defunct.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading

0 comments on commit eff8ff2

Please sign in to comment.