-
Notifications
You must be signed in to change notification settings - Fork 13
/
README.Rmd
117 lines (98 loc) · 7.08 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
---
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
---
<!-- badges: start -->
[](https://doi.org/10.21105/joss.01768)
[](https://github.com/trashbirdecology/bbsAssistant/actions)
[](https://creativecommons.org/publicdomain/zero/1.0/)
[](#contributors)
[](https://github.com/trashbirdecology/bbsAssistant/actions)
<!-- badges: end -->
<img src=".github/figures/logo.png" align="right" height=140/>
## 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/).
<!-- ## Potential Future Developments -->
<!-- - [ ] Functions for creating presence/absence and count matrices for use in JAGS and beyond (see also: https://github.com/trashbirdecology/bbsebird/) -->
<!-- - [ ] Spatial visualization tools -->
<!-- devtools::check(args = c("--no-examples", "--no-tests")) -->
## 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:[email protected]) or submit an [Issue](https://github.com/TrashBirdEcology/bbsAssistant/issues) (preferred).