bbs_build_50: Assemble North American Breeding Bird Survey 50-stop count...
In patrickbarks/bbs: North American Breeding Bird Survey (BBS) in R

Description Usage Arguments Details Value Geographic Subsetting Author(s) References See Also Examples

Assemble North American Breeding Bird Survey 50-stop count data into a data frame, optionally subset to select regions, years, and/or species. The underlying data come from 10 zipped csv files within the BBS folder 50-StopData/. These csv files do not include counts of zero (i.e. when a species is not observed during a given survey), but counts of zero can optionally be built in (see argument zeros).

Note: Without counts of zero the full 50-stop dataset for 2017 includes 3.4 million rows. With zeros it includes 47 million rows, which will take some time to build and require a few gigabytes of memory. If building with zeros, consider subsetting to regions, years, and/or species of interest.

1 2	bbs_build_50(bbs_dir, zeros = FALSE, countries = NULL, states = NULL, bcr = NULL, strata = NULL, aou = NULL, years = NULL)

`bbs_dir`	Local directory from which to load BBS data. Must be an existing directory with the same structure as the USGS BBS directory (ftp://ftpext.usgs.gov/pub/er/md/laurel/BBS/DataFiles/).
`zeros`	Build in counts of zero? Defaults to `FALSE`. (See Details)
`countries`	Vector of country names to subset to. Defaults to all available. Case insensitive. (See section Geographic Subsetting)
`states`	Vector of state/province/territory names to subset to. Defaults to all available. Case insensitive. (See section Geographic Subsetting)
`bcr`	Vector of Bird Conservation Region integer codes to subset to. Defaults to all available. (See section Geographic Subsetting)
`strata`	Vector of physiographic strata integer codes to subset to. Defaults to all available. (See section Geographic Subsetting)
`aou`	Vector of integer species id codes to subset to. Defaults to all available. (See BBS file SpeciesList.txt)
`years`	Vector of survey years to subset to. Defaults to all available.

If zeros = TRUE, counts of zero are built in as follows:

1. Find every unique combination of route-year-rpid matching the given subset arguments (or the whole dataset if no subset arguments given).

2. Find every unique species (aou) that was recorded on those route-year-rpid (subject to aou subset argument, if given).

3. Create a data frame with every combination of those route-year-rpid and aou, and merge with the non-zero count data. Any route-year-rpid-aou rows with missing count data are then filled in with counts of zero.

Note that this method is potentially inefficient in that it will yield counts of zero for species even in regions where they have never been observed.

A data.frame with the following columns (all integer):

`route_data_id`	code for unique combinations of country_num, state, route, rpid, and year
`country_num`	code for country: 124 (Canada), 484 (Mexico), or 840 (United States)
`state_num`	code for state/province/territory (see BBS file RegionCodes.txt)
`route`	code for route (unique within states)
`rpid`	code for Run Protocol ID (see BBS file RunProtocolID.txt)
`year`	survey year
`aou`	species code from American Ornithological Union
`stop_1 ... stop_50`	total individuals of the species recorded on stops 1-10

For country and state names see bbs_meta_regions. For integer bcr codes see bbs_meta_bcr, and for integer strata codes see bbs_meta_strata.

Geographic subsetting may done by countries and/or states OR bcr and/or strata, but not by both. Subsets are additive, so specifying

bbs_build_50('.', countries = 'Canada', states = 'Montana')

will return data for all Canadian provinces/territories plus the state of Montana. Likewise, the following lines are equivalent, and will both return data for all American states:

bbs_build_50('.', countries = 'United States', states = 'Florida')
bbs_build_50('.', countries = 'United States')

Bob O'Hara

Patrick Barks <patrick.barks@gmail.com>

Pardieck, K.L., D.J. Ziolkowski Jr., M. Lutmerding and M.-A.R. Hudson. 2018. North American Breeding Bird Survey Dataset 1966-2017, version 2017.0. U.S. Geological Survey, Patuxent Wildlife Research Center. https://doi.org/10.5066/F76972V8

bbs_download

## Not run: 

# build whole dataset excluding counts of zero
bbs <- bbs_build_50(bbs_dir = '.')

# build with Canadian routes only, including counts of zero
bbs <- bbs_build_50(bbs_dir = '.', zeros = TRUE, countries = 'Canada')

# build for species Gray Jay (aou 4840), including counts of zero
bbs <- bbs_build_50(bbs_dir = '.', zeros = TRUE, aou = 4840)

## End(Not run)