Add ebirdhotspotlist, interfacing ref/hotspot and ref/hotspot/geo

[sebpardo]

This PR adds the ebirdhotspotlist() function, which allows to obtain a list of hotspots in a region (ref/hotspot) or nearby coordinates (ref/hotspot/geo).

Hotspots in a region:

> ebirdhotspotlist("CA-NS-HL")
# A tibble: 220 x 10
   locId locName countryCode subnational1Code subnational2Code   lat   lng latestObsDt
   <chr> <chr>   <chr>       <chr>            <chr>            <dbl> <dbl> <chr>      
 1 L233… Abraha… CA          CA-NS            CA-NS-HL          45.2 -62.6 2020-11-21…
 2 L700… Admira… CA          CA-NS            CA-NS-HL          44.7 -63.7 2020-08-23…
 3 L176… Admira… CA          CA-NS            CA-NS-HL          44.8 -63.1 2021-01-10…
 4 L584… Albro … CA          CA-NS            CA-NS-HL          44.7 -63.6 2020-12-28…
 5 L437… Aldern… CA          CA-NS            CA-NS-HL          44.7 -63.6 2021-01-10…
 6 L122… Armdal… CA          CA-NS            CA-NS-HL          44.6 -63.6 2021-01-21…
 7 L624… Atlant… CA          CA-NS            CA-NS-HL          44.7 -63.3 2020-10-22…
 8 L239… Bald R… CA          CA-NS            CA-NS-HL          44.5 -63.6 2020-11-10…
 9 L759… Bayers… CA          CA-NS            CA-NS-HL          44.6 -63.7 2021-01-16…
10 L642… Beaufo… CA          CA-NS            CA-NS-HL          44.7 -63.5 2020-11-06…
# … with 210 more rows, and 2 more variables: numSpeciesAllTime <int>, locID <chr>

Hotspots by nearby coordinates:

> ebirdhotspotlist(lat = 30, lng = -90, dist = 10)
Coordinates provided instead of region code, locating hostpots using lat/lng
# A tibble: 52 x 10
   locId locName countryCode subnational1Code subnational2Code   lat   lng latestObsDt
   <chr> <chr>   <chr>       <chr>            <chr>            <dbl> <dbl> <chr>      
 1 L602… Algier… US          US-LA            US-LA-071         30.0 -90.1 2020-12-15…
 2 L388… Armstr… US          US-LA            US-LA-071         30.0 -90.1 2021-01-03…
 3 L727… Audubo… US          US-LA            US-LA-071         30.0 -90.0 2021-01-18…
 4 L666… BAEA N… US          US-LA            US-LA-087         30.0 -90.0 2021-01-17…
 5 L666… BAEA N… US          US-LA            US-LA-071         29.9 -90.0 2021-01-18…
 6 L242… Bayou … US          US-LA            US-LA-071         30.0 -90.0 2021-01-16…
 7 L725… Bayou … US          US-LA            US-LA-071         30.1 -89.9 2020-12-29…
 8 L727… Chalme… US          US-LA            US-LA-087         29.9 -90.0 2021-01-17…
 9 L453… City P… US          US-LA            US-LA-071         30.0 -90.1 2020-12-19…
10 L522… City P… US          US-LA            US-LA-071         30.0 -90.1 2020-06-16…
# … with 42 more rows, and 2 more variables: numSpeciesAllTime <int>, locID <chr>

Closes #83.

[sebpardo]

Here it is @dbradnum, in relation to #85.

[dbradnum]

Looks good to me! I'd not even considered the ref/hotspot endpoint, so the change you've proposed is going to cover more ground than mine.

The main thing I did differently was to use the getlatlng() function , so the location gets auto-detected from the user's IP address if lat/lng aren't provided. I also had a couple of checks for valid lat/lng values if the user does provide them.

Both these bits of code were stolen from existing functions, giving me something like this...

geoloc <- c(lat, lng)
  if (is.null(geoloc)) geoloc <- getlatlng()

  if (abs(geoloc[1]) > 90) {
    stop("Please provide a latitude between -90 and 90 degrees.")
  }

  if (abs(geoloc[2]) > 180) {
    stop("Please provide a longitude between -180 and 180 degrees.")
  }

If you adopted this, then I think you could drop the requirement that either a region or a lat/lng pair has to be provided - with none of these, the function would end up using the default radius around the user's IP.

I also spotted the odd duplication of the locID column, and dropped it:

res <- ebird_GET(url, args, key = get_key(), ...)

  # remove locID column which is returned in duplicate by the API
  colToRemove <- "locID"
  if (colToRemove %in% names(res)) {
    res <- select(res, -colToRemove)
  }

[dbradnum]

PS - seeing your change to README.md make me realise that I'd only updated the Rmd, rather than .md - predictably the Rmd wouldn't knit because of our old friend ebirdfreq() . So we need a little change to the .md file to sync things up.

[sebpardo]

@dbradnum: how about I merge this PR, and then you can update this function with your improvements in a new PR? I think it would be good to include that additional functionality, and this way I can keep the ball rolling with all the other edits I need to make to the package before submitting to CRAN.

I'll update all the docs and include that change to README.md once I fix ebirdfreq().

[dbradnum]

Sounds fine - will do.

More generally, I'm happy to help with any other bits and pieces on the package at the moment, so feel free to suggest anything. Given the state of COVID here, we're under pretty tight lockdown at present, so I have more time available when I'd usually be birding!