bbsAssistant: An R package for Downloading and Handling Data and Information from the North American Breeding Bird Survey (BBS)
Last updated: 2022-03-11
This repository contains the development version of bbsAssistant. Please submit Issues here.
This package contains functions for downloading, importing, and munging the official releases of the North American Breeding Bird Survey (BBS) data (retrieved from USGS ScienceBase repository) with the help of package sbtools.
library(bbsAssistant)
# view functions and data in package bbsAssistant
# ls("package:bbsAssistant")bbs <- grab_bbs_data()## bbs_dir not specified. bbs dataset will be saved to data-in/5ea04e9a82cefae35a129d65
# Optional: specify `sb_id` as the USGS ScienceBase identifier for a specific data release. If sb_id is not supplied, will default to the most recent data release.The object resulting from bbsAssistant::import_bbs_data() is a list
comprising the following elements:
names(bbs)## [1] "observations" "routes" "observers" "weather" "species_list"
## [6] "citation" "vehicle_data" "data.dir"
Filter the dataset using your preferred method. A lookup table is provided as a package dataset for filtering by country or state using the BBS codes (see columns CountryNum, StateNum) or ISO alpha codes and names (see columns iso_3155_2, iso_a2, name_fr, name_es):
head(bbsAssistant::region_codes, 3)## CountryNum StateNum State iso_3166_2 iso_a2
## 1 484 1 aguascalientes MX-AGU MX
## 2 484 2 baja california MX-BCN MX
## 3 484 3 baja california sur MX-BCS MX
## name_fr name_es
## 1 Aguascalientes Aguascalientes
## 2 Basse-Californie Baja California
## 3 Basse-Californie du Sud Baja California Sur
View the species lists for your particular dataset by calling:
head(bbs$species_list,3)## # A tibble: 3 x 12
## Seq AOU English_Common_Name French_Common_N~ Spanish_Common_~ ORDER Family
## <chr> <int> <chr> <chr> <chr> <chr> <chr>
## 1 6 1770 Black-bellied Whis~ "Dendrocygne \x~ Dendrocygna aut~ Anse~ Anati~
## 2 7 1780 Fulvous Whistling-~ "Dendrocygne fa~ Dendrocygna bic~ Anse~ Anati~
## 3 8 1760 Emperor Goose "Oie empereur" Anser canagicus Anse~ Anati~
## # ... with 5 more variables: Genus <chr>, Species <chr>, Scientific_Name <chr>,
## # AOU4 <chr>, AOU6 <chr>
or view the most recent species list (may be the same as yours..):
head(bbsAssistant::species_list,3)Keep only Passer domesticus:
# grab the aou code for House Sparrow using common name
hosp.aou.code <- bbs$species_list$AOU[bbs$species_list$English_Common_Name=="House Sparrow"]
# or genus and species epithet
# hosp.aou.code <-
# bbs$species_list$AOU[bbs$species_list$Genus == "Passer" &
# bbs$species_list$Species == "domesticus"]
# filter the observations along BBS "AOU" code:
## note spelling but not capitalization matters.
## can provide species arg as species' common or latin name(s) or as BBS "AOU" code(s)
hosp.df <- munge_bbs_data(bbs_list=bbs, species = hosp.aou.code)## Creating a flat data frame as output object.
# species = c("House SPARROW", "passer Domesticus", hosp.aou.code)) There are currently two primary products released from the USGS that are derived from the annual BBS roadside surveys, the observations data and the analysis results. The datasets (observations, results) are permanently and publicly available at USGS ScienceBase.
The most recent annual releases of the observations and results datasets
are stored as data objects in this package (see data(bbs)) will be
downloaded as the default in this package, but the user has the option
to specify historical dataset releases should they choose. Please see
the function get_bbs_data().
A lookup table containing the available datasets (N = 7) and analysis results will be regularly updated, and comprises the following entries:
List of datasets currently available for download at USGS ScienceBase. Highlighted and bold row indicates the default BBS observations dataset stored internally in the package.| sb_title | release_year | data_type | year_start | year_end | sb_link | sb_item |
|---|---|---|---|---|---|---|
| 2020 Release - North American Breeding Bird Survey Dataset (1966-2019) | 2020 | observations | 1966 | 2019 | sciencebase.gov/catalog/item/5ea04e9a82cefae35a129d65 | 5ea04e9a82cefae35a129d65 |
| 2019 Release - North American Breeding Bird Survey Dataset (1966-2018) | 2019 | observations | 1966 | 2018 | sciencebase.gov/catalog/item/5d65256ae4b09b198a26c1d7 | 5d65256ae4b09b198a26c1d7 |
| 2018 Release - North American Breeding Bird Survey Dataset (1966-2017) | 2018 | observations | 1966 | 2017 | sciencebase.gov/catalog/item/5af45ebce4b0da30c1b448ca | 5af45ebce4b0da30c1b448ca |
| 2017 Release - North American Breeding Bird Survey Dataset (1966-2016) | 2017 | observations | 1966 | 2016 | sciencebase.gov/catalog/item/5cf7d4d5e4b07f02a7046479 | 5cf7d4d5e4b07f02a7046479 |
| 2001-2016 Releases (legacy format) - North American Breeding Bird Survey Dataset | 2016 | observations | 1966 | 2015 | sciencebase.gov/catalog/item/5d00efafe4b0573a18f5e03a | 5d00efafe4b0573a18f5e03a |
| The North American Breeding Bird Survey, Analysis Results 1966 - 2018 | 2020 | usgs_results | 1966 | 2018 | sciencebase.gov/catalog/item/5ea1e02c82cefae35a16ebc4 | 5ea1e02c82cefae35a16ebc4 |
| The North American Breeding Bird Survey, Analysis Results 1966 - 2017 | 2018 | usgs_results | 1966 | 2017 | sciencebase.gov/catalog/item/5eab196d82cefae35a2254e0 | 5eab196d82cefae35a2254e0 |
For the BBS dataset and analysis results, call
citation("bbsAssistant") or see library loading message.
For general use of the R package bbsAssistant and/or companion
paper:
Burnett, J.L., Wszola, L., and Palomo-Muñoz, G. (2019). bbsAssistant: An
R package for downloading and handling data and information from the
North American Breeding Bird Survey: U.S. Geological Survey software
release, https://doi.org/10.5066/P93W0EAW. or Burnett, J.L., Wszola,
L., and Palomo-Muñoz, G. (2019). bbsAssistant: An R package for
downloading and handling data and information from the North American
Breeding Bird Survey. Journal of Open Source Software, 4(44), 1768,
https://doi.org/10.21105/joss.01768
Please note that the bbsAssistant project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms. For questions, comments, or issues, feel free to email the maintainer Jessica Burnett or submit an Issue (preferred).