Define a filter for the eBird Basic Dataset (EBD) based on a set of states. This function only defines the filter and, once all filters have been defined, auk_filter() should be used to call AWK and perform the filtering.

auk_state(x, state, replace = FALSE)

Arguments

x

auk_ebd or auk_sampling object; reference to file created by auk_ebd() or auk_sampling().

state

character; states to filter by. eBird uses 4 to 6 character state codes consisting of two parts, the 2-letter ISO country code and a 1-3 character state code, separated by a dash. For example, "US-NY" corresponds to New York State in the United States. Refer to the data frame ebird_states for look up state codes.

replace

logical; multiple calls to auk_state() are additive, unless replace = FALSE, in which case the previous list of states to filter by will be removed and replaced by that in the current call.

Value

An auk_ebd object.

Details

It is not possible to filter by both country and state, so calling auk_state() will reset the country filter to all countries, and vice versa.

This function can also work with on an auk_sampling object if the user only wishes to filter the sampling event data.

Examples

# state codes for a given country can be looked up in ebird_states
dplyr::filter(ebird_states, country == "Costa Rica")
#> # A tibble: 7 × 4
#>   country    country_code state      state_code
#>   <chr>      <chr>        <chr>      <chr>     
#> 1 Costa Rica CR           Alajuela   CR-A      
#> 2 Costa Rica CR           Cartago    CR-C      
#> 3 Costa Rica CR           Guanacaste CR-G      
#> 4 Costa Rica CR           Heredia    CR-H      
#> 5 Costa Rica CR           Limón      CR-L      
#> 6 Costa Rica CR           Puntarenas CR-P      
#> 7 Costa Rica CR           San José   CR-SJ     
# choose texas, united states and puntarenas, cost rica
states <- c("US-TX", "CR-P")
system.file("extdata/ebd-sample.txt", package = "auk") %>%
  auk_ebd() %>%
  auk_state(states)
#> Input 
#>   EBD: /usr/local/lib/R/site-library/auk/extdata/ebd-sample.txt 
#> 
#> Output 
#>   Filters not executed
#> 
#> Filters 
#>   Species: all
#>   Countries: all
#>   States: CR-P, US-TX
#>   Counties: all
#>   BCRs: all
#>   Bounding box: full extent
#>   Years: all
#>   Date: all
#>   Start time: all
#>   Last edited date: all
#>   Protocol: all
#>   Project code: all
#>   Duration: all
#>   Distance travelled: all
#>   Records with breeding codes only: no
#>   Complete checklists only: no
  
# alternatively, without pipes
ebd <- auk_ebd(system.file("extdata/ebd-sample.txt", package = "auk"))
auk_state(ebd, states)
#> Input 
#>   EBD: /usr/local/lib/R/site-library/auk/extdata/ebd-sample.txt 
#> 
#> Output 
#>   Filters not executed
#> 
#> Filters 
#>   Species: all
#>   Countries: all
#>   States: CR-P, US-TX
#>   Counties: all
#>   BCRs: all
#>   Bounding box: full extent
#>   Years: all
#>   Date: all
#>   Start time: all
#>   Last edited date: all
#>   Protocol: all
#>   Project code: all
#>   Duration: all
#>   Distance travelled: all
#>   Records with breeding codes only: no
#>   Complete checklists only: no