bbsAssistant: An R package for Downloading and Handling Data and Information from the North American Breeding Bird Survey (BBS)

Last updated: 2022-03-11

About

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.

Quick Start

library(bbsAssistant)
# view functions and data in package bbsAssistant
# ls("package:bbsAssistant")

Download, Unpack, and Import the Most Recent Dataset

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"

Filtering by State/Region

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

Filter on species names

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

BBS Data Availability (including sb_id)

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:

Citations

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

Contributing

Code of Conduct

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