In trashbirdecology/bbsAssistant: Download and Munge Data and Information from the North American Breeding Bird Survey

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

remotes::install_github("trashbirdecology/bbsAssistant", 
                         ref="main", # change to main for releases
                         force=TRUE) # force=TRUE to get most recent dev version

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

Download, Unpack, and Import the Most Recent Dataset

bbs <- grab_bbs_data()
# 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)

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)

Filter on species names

View the species lists for your particular dataset by calling:

head(bbs$species_list,3)

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"]
hofi          <- bbs$species_list$Scientific_Name[bbs$species_list$English_Common_Name=="House Finch"]
# 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 = c(hosp.aou.code, hofi))
                          # 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().

datasets <- bbsAssistant::sb_items

A lookup table containing the available datasets (N = r length(unique(datasets$sb_item))) and analysis results will be regularly updated, and comprises the following entries:

library(magrittr)
library(dplyr)
library(kableExtra)
datasets %>% select(-legacy_format, -sb_parent) %>%  
  relocate(sb_item, .after = last_col()) %>%
  kable(caption="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.") %>% 
  kable_styling(bootstrap_options = "striped", full_width = TRUE, position = "left") %>% 
  column_spec(1, width = "100em") %>% 
  row_spec(1, background = "yellow", bold = TRUE)

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

trashbirdecology/bbsAssistant documentation built on May 22, 2022, 6:08 a.m.