bbsAssistant

bbsAssistant: An R package for downloading and handling data and information from the North American Breeding Bird Survey - Published in JOSS (2019)

https://github.com/trashbirdecology/bbsassistant

Keywords

Repository

An R package for downloading and handling data and information from the North American Breeding Bird Survey.

README.Rmd

---
title: "**bbsAssistant**: An R package for Downloading and Handling Data and Information from the North American Breeding Bird Survey (BBS)"
date: "Last updated: `r Sys.Date()`"
bibliography: .github/paper/paper.bib
output: github_document
always_allow_html: true
---

[![DOI](https://joss.theoj.org/papers/10.21105/joss.01768/status.svg?style=flat-square&logo=appveyor)](https://doi.org/10.21105/joss.01768)
[![R build status](https://github.com/trashbirdecology/bbsAssistant/workflows/R-CMD-check/badge.svg?style=flat-square&logo=appveyor)](https://github.com/trashbirdecology/bbsAssistant/actions)
[![License: CC0](https://img.shields.io/badge/License-CC0%201.0-lightgrey.svg?style=flat-square&logo=appveyor)](https://creativecommons.org/publicdomain/zero/1.0/)
[![Contributors](https://img.shields.io/badge/all_contributors-8-lightgrey.svg?style=flat-square&logo=appveyor)](#contributors)
[![R-CMD-check](https://github.com/trashbirdecology/bbsAssistant/workflows/R-CMD-check/badge.svg)](https://github.com/trashbirdecology/bbsAssistant/actions)



## About
This repository contains the development version of __bbsAssistant__. Please submit [Issues here](https://github.com/TrashBirdEcology/bbsAssistant/issues). 

This package contains functions for downloading, importing, and munging the official releases of the [North American Breeding Bird Survey](https://www.pwrc.usgs.gov/bbs/) (BBS) data (retrieved from  USGS ScienceBase repository) with the help of package [sbtools](https://cran.r-project.org/package=sbtools/). 







## Quick Start
```{r install, echo=FALSE, warning=FALSE, message=FALSE, eval=FALSE}
remotes::install_github("trashbirdecology/bbsAssistant", 
                         ref="main", # change to main for releases
                         force=TRUE) # force=TRUE to get most recent dev version
```


```{r libs, echo=TRUE, warning=FALSE, message=FALSE, eval=TRUE}
library(bbsAssistant)
# view functions and data in package bbsAssistant
# ls("package:bbsAssistant")
```

## Download, Unpack, and Import the Most Recent Dataset
```{r grab_bbs_data, echo=TRUE, warning=FALSE, message=FALSE, eval=TRUE}
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:
```{r view, echo=TRUE, warning=FALSE, message=FALSE, eval=TRUE}
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):
```{r regioncodes, echo=TRUE, warning=FALSE, message=FALSE, eval=TRUE}
head(bbsAssistant::region_codes, 3)
```
### Filter on species names
View the species lists for your particular dataset by calling:
```{r}
head(bbs$species_list,3)
```

or view the most recent species list (may be the same as yours..):
```{r, eval=FALSE}
head(bbsAssistant::species_list,3)
```

Keep only _Passer domesticus_:
```{r filter-hosp}
# 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](https://www.sciencebase.gov/catalog/item/52b1dfa8e4b0d9b325230cd9) and the analysis results. The datasets (observations, results) are permanently and publicly available at [USGS ScienceBase](https://www.sciencebase.gov/). 

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

```{r dataset-lookup,  eval=TRUE, message=FALSE, warning=FALSE, echo=FALSE}
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: 
```{r datasets, eval=TRUE, message=FALSE, warning=FALSE, echo=FALSE}
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](https://contributor-covenant.org/version/2/0/CODE_OF_CONDUCT.html). 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](mailto:jburnett@usgs.gov) or submit an [Issue](https://github.com/TrashBirdEcology/bbsAssistant/issues) (preferred).

Owner

JOSS Publication

bbsAssistant: An R package for downloading and handling data and information from the North American Breeding Bird Survey

Published

December 04, 2019

DOI

10.21105/joss.01768

Volume 4, Issue 44, Page 1768

Authors

Jessica L. Burnett
Science Analytics and Synthesis, Core Science Systems, U.S. Geological Survey, Denver, Colorado, USA

Lyndsie Wszola
School of Natural Resources, University of Nebraska, Lincoln, Nebraska, USA, School of Biological Sciences, University of Nebraska, Lincoln, Nebraska, USA

Gabriela Palomo-Muñoz
School of Natural Resources, University of Nebraska, Lincoln, Nebraska, USA

Editor

Kristen Thyng

Tags

breeding bird survey data retriever ecology point counts

View PDF Review Thread Software Archive

GitHub Events

Committers

Last synced: 7 months ago

Issues and Pull Requests

Last synced: 6 months ago