bbsBayes: An R Package for Hierarchical Bayesian Analysis of North American Breeding Bird Survey Data
Switch branches/tags
Nothing to show
Clone or download
Latest commit aa2dc9c Nov 12, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
R
data
inst
man
.Rbuildignore
.gitignore
.travis.yml
DESCRIPTION Emergency commit to remove beta from description, fixes #73 Nov 12, 2018
LICENSE
NAMESPACE
README.md
bbsBayes.Rproj

README.md

bbsBayes

Build Status CRAN_Status_Badge

Overview

bbsBayes is a package to perform hierarchical Bayesian analysis of North American Breeding Bird Survey (BBS) data. 'bbsBayes' will run a full model analysis for one or more species that you choose, or you can take more control and specify how the data should be stratified, prepared for JAGS, or modelled.

Installation

The updated beta version of v1.0.0 is now out!

# To install v1.0.0-beta.2 from Github:
install.packages("devtools")
library(devtools)
devtools::install_github("BrandonEdwards/bbsBayes", ref = "v1.0.0-beta.2")

Alternatively, you could install the less-stable development version.

# To install the development version from GitHub:
install.packages("devtools")
library(devtools)
devtools::install_github("BrandonEdwards/bbsBayes")

Usage

bbsBayes provides functions for every stage of Breeding Bird Survey data analysis.

Data Retrieval

You can download BBS data by running fetch_bbs_data and saving it to a variable. You must agree to the terms and conditions of the data usage before downloading.

bbs_data <- fetch_bbs_data()

Data Preparation

Stratification

Stratification plays an important role in trend analysis. Use the stratify() function on the bbs_data you downloaded, and specify how you would like to stratify your data by. Set stratify_by by choosing one of the following:

  • bbs_cws -- Political region X Bird Conservation region intersection (CWS method)
  • bbs_usgs -- Political region X Bird Conservation region intersection (USGS method)
  • bcr -- Bird Conservation Region only
  • state -- Political Region only
  • latlong -- Degree blocks (1 degree of latitude X 1 degree of longitude)
strat_data <- stratify(bbs_data, stratify_by = "bcr")

Jags Data

JAGS models require the data to be sent as a data frame depending on how the model is set up. prepare_jags_data subsets the stratified data based on species and wrangles relevent data to use for JAGS models.

jags_data <- prepare_jags_data(strat_data, 
                               species_to_run = "Spruce Grouse", 
                               model = "slope")

MCMC

Once the data has been prepared for JAGS, the model can be run. The following will run MCMC with default number of iterations.

mod <- run_model(jags_data = jags_data)

Alternatively, you can set how many iterations, burn-in steps, or adapt steps to use

mod <- run_model(jags_data = jags_data,
                 n_burnin = 1000,
                 n_iter=1000,
                 n_adapt = 500)

Model Analysis

There are a number of tools available to analyse the posterior chain output from the MCMC model. The main metric is annual trend, which can be calculated for each stratum:

strat_indices <- generate_strata_indices(mod)
strat_trend <- generate_strata_trends(indices = strat_indices)

These trends can be mapped

generate_map(strat_trend, stratify_by = "bcr")

Which produces

There are numerous other functions available for analysis of the data.

Lifecycle

lifecycle

bbsBayes is currently going through multiple internal code reviews, tests, and API updates. Most likely, the API you use today will be slightly different than the one you use tomorrow.

The near-future goal is to publish a maturing version on CRAN. Be sure to check back for updates!