ebirdregion() output sometimes includes exoticCategory field

[sebpardo]

I noticed that sometimes the test for this function fails due to a mismatch between the expected and returned number of columns. What's happening if that if the query includes exotic species, then an additional field named exoticCategory is being returned. This might not be behaviour exclusive to ebirdregion().

library(rebird)
library(dplyr)

out <- ebirdregion(loc = 'US', species = 'btbwar', back = 14.75, max = 2)
res <- ebirdregion(loc = 'US-OR-029', max = 3)

names(out)
#>  [1] "speciesCode"     "comName"         "sciName"         "locId"          
#>  [5] "locName"         "obsDt"           "howMany"         "lat"            
#>  [9] "lng"             "obsValid"        "obsReviewed"     "locationPrivate"
#> [13] "subId"
names(res)
#>  [1] "speciesCode"     "comName"         "sciName"         "locId"          
#>  [5] "locName"         "obsDt"           "howMany"         "lat"            
#>  [9] "lng"             "obsValid"        "obsReviewed"     "locationPrivate"
#> [13] "subId"           "exoticCategory"

Need to include this field in the documentation for this function, update tests, and perhaps have a quick look around to see if any other functions are also showing this behaviour.

[slager]

I suspect this could be widespread-ish across rebird functions.

See also: 6097b66, 0aeb90f

[slager]

Which do you think is a better approach @sebpardo?

1. Only return exoticCategory if present in the API result, and leave it out if not.
2. Do this before returning the data frame, for all functions that might possibly return exoticCategory:

if(! 'exoticCategory' %in% names(df)) df$exoticCategory <- NA_character_

1 sticks closer to what the API actually returns, but 2 produces more consistent results. I probably favor number 1, which is what I'm pretty sure is what you were proposing along with adding exoticCategory to the documentation for any functions that might return it and making sure no tests depend on it being present or absent in the output.

[sebpardo]

I also prefer approach 1. I think it's relatively easy to fix tests to accommodate returns of different numbers of columns, and add something along these lines to the documentation of those functions:

#' @return "exoticCategory":  If applicable, exotic species category. This column will be provided 
#'    if there are exotics or introduced species in the query. Return values are "N" for naturalized, 
#'    "P" for provisional, "X" for escapee, and NA for native. For more information see 
#'    \url{https://ebird.org/news/important-changes-to-exotic-species-in-ebird}.

EDIT: This other url might be better?: https://support.ebird.org/en/support/solutions/articles/48001218430

As a side note, here's a checklist with all four categories, I hope there aren't more:

library(rebird)
library(dplyr)

ebirdchecklist("S165343164") |>
  mutate(name = tax[which(tax$speciesCode %in% speciesCode), "comName"]) |>
  select(name, exoticCategory)
#> # A tibble: 6 × 2
#>   name$comName         exoticCategory
#>   <chr>                <chr>         
#> 1 Red-crowned Parrot   N             
#> 2 Lilac-crowned Parrot P             
#> 3 Red-lored Parrot     P             
#> 4 Yellow-headed Parrot X             
#> 5 Green Parakeet       N             
#> 6 Chihuahuan Raven     <NA>

[slager]

I think these are the functions that can (sometimes?) return exoticCategory:

• ebirdchecklist
• ebirdgeo
• ebirdhistorical
• ebirdnotable
• ebirdregion
• nearestobs

The column userDoNotCount also appears in the ebirdchecklist() output when a species is exotic. Either this was recently added to the API or I missed it when I wrote the documentation for ebirdchecklist().

[RichardLitt]

I would like to help with this work, but I think that I would be able to help much more efficiently if someone could pair program with me - for perhaps as short as 15 minutes - over a video call to help me understand how to run and test R PRs. I am on the New Zealand time zone.

This may be a stretch, but I figured it can't hurt to ask. :)

[RichardLitt]

"Sometimes" is accurate. ebirdchecklist, for instance, doesn't always return it:

> ebirdchecklist("S196819012") |>
+   mutate(name = tax[which(tax$speciesCode %in% speciesCode), "comName"]) |>
+   select(name, exoticCategory)
Error in `select()`:
! Can't subset columns that don't exist.
✖ Column `exoticCategory` doesn't exist.
Run `rlang::last_trace()` to see where the error occurred.

nearestobs can also return it:

> nearestobs('houspa', 42, -76)
# A tibble: 17 × 14
   speciesCode comName       sciName           locId     locName                          obsDt howMany   lat   lng obsValid obsReviewed locationPrivate subId exoticCategory
   <chr>       <chr>         <chr>             <chr>     <chr>                            <chr>   <int> <dbl> <dbl> <lgl>    <lgl>       <lgl>           <chr> <chr>         
 1 houspa      House Sparrow Passer domesticus L3583220  SUNY Broome Community College    2024…       3  42.1 -75.9 TRUE     FALSE       FALSE           S197… N             
...

I am opening a PR.