The functions listed below are deprecated and will be defunct in
the near future. When possible, alternative functions with similar
functionality are also mentioned. Help pages for deprecated functions are
available at help("-deprecated").
generate_cont_indices creates a data frame of the strata-weighed
continental indices by year. This data frame can then be used to
generate a population trajectory of the species.
generate_cont_trend calculates the geometric mean annual changes in population size.
generate_regional_indices creates a data frame of the strata-weighted
regional indices by year. This data frame can then be used to
generate a population trajectory of the species.
generate_regional_trends calculates the geometric mean annual changes in population size for composite regions.
generate_strata_indices creates a data frame of indices by year,
factored by each stratum. These indicies can be used to generate
trajectory plots of the species for each strata.
generate_strata_trends creates a data frame of trends by year,
factored by each stratum. These trends are calculated using the indices
generated by generate_strata_indices.
p_waic calculates effective number of parameters. This is
used as a bias adjustment factor in the calculation of WAIC
in the function waic.
Generates the trajectory plot of continental indices.
prepare_jags_data subsets raw BBS data by selected species and
and wrangles stratified data for use as input to run JAGS models.
waic returns the Watanabe–Akaike information criterion (WAIC) for the
supplied model. WAIC is a generalization of the Akaike information
criterion onto singular statistical model.
generate_cont_indices(
jags_mod = NULL,
quantiles = c(0.025, 0.05, 0.25, 0.75, 0.95, 0.975),
alternate_n = "n"
)generate_cont_trend(
indices = NULL,
min_year = NULL,
max_year = NULL,
quantiles = c(0.025, 0.05, 0.25, 0.75, 0.95, 0.975),
slope = FALSE
)
generate_regional_indices(
jags_mod = NULL,
jags_data = NULL,
quantiles = c(0.025, 0.05, 0.25, 0.75, 0.95, 0.975),
regions = c("stratum", "continental"),
alternate_n = "n",
startyear = NULL,
drop_exclude = FALSE,
max_backcast = NULL,
alt_region_names = NULL
)
generate_regional_trends(
indices = NULL,
Min_year = NULL,
Max_year = NULL,
quantiles = c(0.025, 0.05, 0.25, 0.75, 0.95, 0.975),
slope = FALSE,
prob_decrease = NULL,
prob_increase = NULL
)
generate_strata_indices(
jags_mod = NULL,
quantiles = c(0.025, 0.05, 0.25, 0.75, 0.95, 0.975),
alternate_n = "n"
)
generate_strata_trends(
indices = NULL,
min_year = NULL,
max_year = NULL,
quantiles = c(0.025, 0.05, 0.25, 0.75, 0.95, 0.975),
slope = FALSE
)
p_waic(jags_data = NULL, jags_mod = NULL, pointwise = FALSE)
plot_cont_indices(
indices_list = NULL,
select = FALSE,
ci_width = 0.95,
min_year = NULL,
max_year = NULL,
species = "",
title_size = 20,
axis_title_size = 18,
axis_text_size = 16,
add_observed_means = FALSE
)
prepare_jags_data(
strat_data = NULL,
species_to_run = NULL,
model = NULL,
heavy_tailed = FALSE,
n_knots = NULL,
min_year = NULL,
max_year = NULL,
min_n_routes = 3,
min_max_route_years = 3,
min_mean_route_years = 1,
strata_rem = NULL,
quiet = FALSE,
...
)
waic(jags_data = NULL, jags_mod = NULL)
List of 6 objects:
dataframe with the following columns
Year of particular index
Region name
Strata-weighted count index
quantiles of the posterior distribution
array of all samples from the posterior distribution
data frame of the strata names and area weights used to calculate the continental estimates
first year used in the model, scale 1:length of time-series
last year used in the model, scale 1:length of time-series
first year used in the model, scale 1966:2018
Numeric percentage of trend
List of 6 objects
dataframe with the following columns
Year of particular index
Region name
Long name for region
Type of region including continental, national,Province_State,BCR, bcr_by_country, or stratum
Strata included in the annual index calculations
Strata potentially excluded from the annual index calculations because they have no observations of the species in the first part of the time series, see arguments max_backcast and startyear
Strata-weighted count index
quantiles of the posterior distribution
Mean of the observed annual counts of birds across all routes and all years. An alternative estimate of the average relative abundance of the species in the region and year. Differences between this and the annual indices are a function of the model. For composite regions (i.e., anything other than stratum-level estimates) this average count is calculated as an area-weighted average across all strata included
Number of BBS routes that contributed data for this species, region, and year
Number of BBS routes on which this species was observed (i.e., count is > 0) in this region and year
approximate annual average proportion of the covered species range that is free of extrapolated population trajectories. e.g., 1.0 = data cover full time-series, 0.75 = data cover 75 percent of time-series. Only calculated if max_backcast != NULL
array of all samples from the posterior distribution
data frame of the strata names and area weights used to calculate the continental estimates
first year used in the summary, scale 1:length of time-series
last year used in the summary, scale 1:length of time-series
first year used in the summary, scale 1966:2018
Dataframe with one row for each region included in indices object, and columns including:
first year of the trend
last year of the trend
short name of the region
Long name for region
Type of region including continental, national,Province_State,BCR, bcr_by_national, or stratum
Strata included in the trend and annual index calculations
Strata potentially excluded from the trend and annual index calculations because they have no observations of the species in the first part of the time series
Estimated mean annual percent change over the trend time-period (i.e., Start_year - End_year), according to an endpoint comparison of annual index in Start_year and the annual index in End_year
quantiles of the posterior distribution of Trend estimates, matching levels included in the quantiles argument
Estimated total percent change over the trend time-period
quantiles of the posterior distribution of Percent Change estimates, matching levels included in the quantiles argument
Estimated mean annual percent change over the trend time-period, according to the slope of a linear regression through the log-transformed annual indices
quantiles of the posterior distribution of Percent Change estimates, matching levels included in the quantiles argument
proportion of the posterior distribution of Percent_Change that is below the percentage values supplied in prob_decrease
proportion of the posterior distribution of Percent_Change that is above the percentage values supplied in prob_increase
Mean of the annual index values across all years. An estimate of the average relative abundance of the species in the region. Can be interepreted as the predicted average count of the species in an average year on an average route by an average observer, for the years, routes, and observers in the existing data
Mean of the observed annual counts of birds across all routes and all years. An alternative estimate of the average relative abundance of the species in the region. For composite regions (i.e., anything other than stratum-level estimates) this average count is calculated as an area-weighted average across all strata included
The number of strata included in the region
Width (in percent/year) of the credible interval on the Trend calculation. Calculated for the widest credible interval requested in quantiles argument. Default is 95 percent CI (i.e., Trend_Q0.975 - Trend_Q0.025)
Width (in percent/year) of the credible interval on the Trend calculation for the slope-based trend. Calculated for the widest credible interval requested in quantiles argument. Default is 95 percent CI (i.e., Slope_Trend_Q0.975 - Slope_Trend_Q0.025)
The number of unique BBS routes included in the trend calculation for this region and species
The average number of BBS routes across years contributing data for this region and species
approximate proportion of the included species range*years that are free of extrapolated population trajectories e.g., 1.0 = data cover full time-series, 0.75 = data cover 75 percent of time-series. Only calculated if max_backcast != NULL
List of 6 objects:
dataframe with the following columns
Year of particular index
Region name
Strata-weighted count index
quantiles of the posterior distribution
array of all samples from the posterior distribution
data frame of the strata names and area weights used to calculate the continental estimates
first year used in the model, scale 1:length of time-series
last year used in the model, scale 1:length of time-series
first year used in the model, scale 1966:2018
Data frame of 2 variables:
Name of the stratum
Percent change from the minimum year to maximum year
Data frame of pointwise pWAIC by count if pointwise
is set to TRUE. Double precision numerical value of pWAIC if
pointwise is set to FALSE.
ggplot of continental indices
List of data to be used in JAGS, including:
The model to be used in JAGS
Logical indicating whether the extra-Poisson error distribution should be modeled as a t-distribution
if heavy_tailed is TRUE, minimum value for truncated gamma on DF of t-distribution noise default is 0 and user must change manually after function is run
The number of counts containing useful data for the species
The number of strata used in the analysis
Minimum year used
Maximum year used
Proportion of routes in each strata with species obervation
Vector of counts for the species
Vector of strata to be used in the analysis
Vector of unique observer-route pairings
Vector of years for each count
Vector of indicator variables as to whether an observer was a first year
vector of numeric month of observation
vector of numeric day of observation
Total number of observer-route pairings
Median of all years (ymin:ymax), included only with slope model
Number of knots to use for smooting functions, included only with GAM
Basis function for n smoothing functions, included only with GAM
Double precision numerical value
JAGS list generated by run_model
vector of quantiles to be sampled from the posterior distribution Defaults to c(0.025,0.05,0.25,0.5,0.75,0.95,0.975)
text string indicating the name of the alternative approach to calculating an annual index, Default is "n"
Stratum indices generated by generate_strata_indices
Minimum year to keep in analysis
Maximum year to keep in analysis
Logical, if TRUE, calculates an alternative trend metric, the slope of a log-linear regression through the annual indices. Default FALSE
Data prepared by prepare_jags_data, used
for input to the JAGS model
vector selcting regional compilation(s) to calculate. Default is "continental","stratum", options also include "national", "prov_state", "bcr", and "bcr_by_country" for the stratifications that include areas that align with those regions.
Optional first year for which to calculate the annual indices if a trajectory for only the more recent portion of the time series is desired. This is probably most relevant if max_backcast is set and so trajectories for different time-periods could include a different subset of strata (i.e., strata removed)
logical indicating if the strata that exceed the max_backcast threshold should be excluded from the calculations, Default is FALSE (regions are flagged and listed but not dropped)
an optional integer indicating the maximum number of years to backcast the stratum-level estimates before the first year in which the species was observed on any route in that stratum. 5 is used in the CWS national estimates. If the observed data in a given stratum do not include at least one non-zero observation of the species between the first year of the BBS and startyear+max_backcast, the stratum is flagged within the relevant regional summary. Default value, NULL ignores any backcasting limit (i.e., generates annual indices for the entire time series, regardless of when the species was first observed)
Optional dataframe indicating the strata to include in a custom spatial summary. Generate the basic dataframe structure with the extract_strata_areas function, then modify with an additional column indicating the strata to include in a custom spatial summary
Minimum year to calculate trends from (e.g., 1970). Default is NULL, in which case the trend is calculated from the first year of the time-series of the supplied annual_indices file
Maximum year to calculate trends to (e.g., 2018). Default is NULL, in which case the trend is calculated up to the last year of the time-series of the supplied annual_indices file
Optional vector of percent-change values to calculate the posterior probabilities that the population has decreased by at least this much (e.g., prob_decrease = c(50) would result in a calculation of the probability that the population has decreased by more than 50 percent over the period of the trend, i.e., less than half the population remains. Default is NULL, in which case no probability of decrease is calculated.
Optional vector of percent-change values to calculate the posterior probabilities that the population has increased by at least this much (e.g., prob_increase = c(100) would result in a calculation of the probability that the population has incrased by more than 100 percent, i.e., doubled, over the period of the trend. Default is NULL, in which case no probability of increase is calculated.
If set to TRUE, a data frame is returned
that contains the pointwise LPPD for each count. Defaults
to FALSE
List of indices of annual abundance and other results produced by
generate_cont_indices
logical flag to indicate if the continental data need to be selected out of an indices_list object that includes stratum, national, or other region-types. Default is FALSE
quantile to define the width of the plotted credible interval. Defaults to 0.95, lower = 0.025 and upper = 0.975
Species name to be added onto the plot
Specify font size of plot title. Defaults to 20
Specify font size of axis titles. Defaults to 18
Specify font size of axis text. Defaults to 16
Should the plot include points indicated the observed mean counts. Defaults to FALSE. Note: scale of observed means and annual indices may not match due to imbalanced sampling among strata
Large list of stratified data returned by stratify()
Character string of the English name of the species to run
Character string of model to be used. Options are "slope", "firstdiff", "gam", "gamye.
Logical indicating whether the extra-Poisson error distribution should be modeled as a t-distribution, with heavier tails than the standard normal distribution. Default is currently FALSE, but recent results suggest users should strongly consider setting this to TRUE, even though it requires much longer convergence times
Number of knots to be used in GAM function
Minimum routes per strata where species has been observed. Defaults to 3
Minimum number of years with non-zero observations of species on at least 1 route. Defaults to 3
Minimum average of years per route with the species observed. Defaults to 1.
Strata to remove from analysis. Defaults to NULL
Should progress bars be suppressed?
Additional arguments
For generate_cont_indices(), use
generate_indices(regions = "continental").
For generate_cont_trend(), use
generate_trends().
For generate_regional_indices(), use
generate_indices().
For generate_regional_trends(), use
generate_trends().
For generate_strata_indices(), use
generate_indices(regions = "stratum").
For generate_strata_trends(), use
generate_trends().
WAIC should no longer be used for BBS data. Cross validation should be used instead.
For plot_cont_indices(), use plot_indices().
For prepare_jags_data(), use
prepare_data(sampler = "jags", ...).
WAIC should no longer be used for BBS data. Cross validation should be used instead.
NOTE: in order to calculated pWAIC, the model MUST track the parameter
"lambda". In species that are data-rich, such as Wood Thrush,
this produces extremely large JAGS objects, and takes up a considerable
amount of memory when simulating with run_model
NOTE: in order to calculated WAIC, the model MUST track the parameter
"lambda". In species that are data-rich, such as Wood Thrush,
this produces extremely large JAGS objects, and takes up a considerable
amount of memory when simulating with run_model
See examples for details.
generate_cont_indices
generate_cont_trend
generate_regional_indices
generate_regional_trends
generate_strata_indices
generate_strata_trends
p_waic
plot_cont_indices
prepare_jags_data
waic
# Toy example with Pacific Wren sample data
# First, stratify the sample data
strat_data <- stratify(by = "bbs_cws", sample_data = TRUE)
# Prepare the stratified data for use in a JAGS model. In this
# toy example, we will set the minimum year as 2009 and
# maximum year as 2018, effectively only setting up to
# model 10 years of data. We will use the "first difference
# model.
jags_data <- prepare_jags_data(strat_data = strat_data,
species_to_run = "Pacific Wren",
model = "firstdiff",
min_year = 2009,
max_year = 2018)
# You can also specify the GAM model, with an optional number of
# knots to use for the GAM basis.
# By default, the number of knots will be equal to the floor
# of the total unique years for the species / 4
jags_data <- prepare_jags_data(strat_data = strat_data,
species_to_run = "Pacific Wren",
model = "gam",
n_knots = 9)
Run the code above in your browser using DataLab