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().