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.

See also

Examples

# state codes for a given country can be looked up in ebird_states dplyr::filter(ebird_states, country == "Costa Rica")
#> # A tibble: 7 x 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: /cache/auk/extdata/ebd-sample.txt #> #> Output #> Filters not executed #> #> Filters #> Species: all #> Countries: all #> States: CR-P, US-TX #> BCRs: all #> Bounding box: full extent #> 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: /cache/auk/extdata/ebd-sample.txt #> #> Output #> Filters not executed #> #> Filters #> Species: all #> Countries: all #> States: CR-P, US-TX #> BCRs: all #> Bounding box: full extent #> 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