bbsBayes-deprecated: Deprecated functions in package 'bbsBayes'.

In BrandonEdwards/bbsBayes: Hierarchical Bayesian Analysis of North American BBS Data

Deprecated functions in package bbsBayes.

Description

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.

Usage

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)

Arguments

jags_mod	JAGS list generated by run_model
quantiles	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)
alternate_n	text string indicating the name of the alternative approach to calculating an annual index, Default is "n"
indices	Stratum indices generated by generate_strata_indices
min_year	Minimum year to keep in analysis
max_year	Maximum year to keep in analysis
slope	Logical, if TRUE, calculates an alternative trend metric, the slope of a log-linear regression through the annual indices. Default FALSE
jags_data	Data prepared by prepare_jags_data, used for input to the JAGS model
regions	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.
startyear	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)
drop_exclude	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)
max_backcast	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)
alt_region_names	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
Min_year	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
Max_year	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
prob_decrease	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.
prob_increase	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.
pointwise	If set to TRUE, a data frame is returned that contains the pointwise LPPD for each count. Defaults to FALSE
indices_list	List of indices of annual abundance and other results produced by generate_cont_indices
select	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
ci_width	quantile to define the width of the plotted credible interval. Defaults to 0.95, lower = 0.025 and upper = 0.975
species	Species name to be added onto the plot
title_size	Specify font size of plot title. Defaults to 20
axis_title_size	Specify font size of axis titles. Defaults to 18
axis_text_size	Specify font size of axis text. Defaults to 16
add_observed_means	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
strat_data	Large list of stratified data returned by stratify()
species_to_run	Character string of the English name of the species to run
model	Character string of model to be used. Options are "slope", "firstdiff", "gam", "gamye.
heavy_tailed	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
n_knots	Number of knots to be used in GAM function
min_n_routes	Minimum routes per strata where species has been observed. Defaults to 3
min_max_route_years	Minimum number of years with non-zero observations of species on at least 1 route. Defaults to 3
min_mean_route_years	Minimum average of years per route with the species observed. Defaults to 1.
strata_rem	Strata to remove from analysis. Defaults to NULL
quiet	Should progress bars be suppressed?
...	Additional arguments

Details

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.

Value

List of 6 objects:

data_summary	dataframe with the following columns
Year	Year of particular index
Region	Region name
Index	Strata-weighted count index
additional columns for each of the values in quantiles	quantiles of the posterior distribution
samples	array of all samples from the posterior distribution
area-weights	data frame of the strata names and area weights used to calculate the continental estimates
y_min	first year used in the model, scale 1:length of time-series
y_max	last year used in the model, scale 1:length of time-series
startyear	first year used in the model, scale 1966:2018

Numeric percentage of trend

List of 6 objects

data_summary	dataframe with the following columns
Year	Year of particular index
Region	Region name
Region_alt	Long name for region
Region_type	Type of region including continental, national,Province_State,BCR, bcr_by_country, or stratum
Strata_included	Strata included in the annual index calculations
Strata_excluded	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
Index	Strata-weighted count index
additional columns for each of the values in quantiles	quantiles of the posterior distribution
obs_mean	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
nrts	Number of BBS routes that contributed data for this species, region, and year
nnzero	Number of BBS routes on which this species was observed (i.e., count is > 0) in this region and year
backcast_flag	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
samples	array of all samples from the posterior distribution
area-weights	data frame of the strata names and area weights used to calculate the continental estimates
y_min	first year used in the summary, scale 1:length of time-series
y_max	last year used in the summary, scale 1:length of time-series
startyear	first year used in the summary, scale 1966:2018

Dataframe with one row for each region included in indices object, and columns including:

Start_year	first year of the trend
End_year	last year of the trend
Region	short name of the region
Region_alt	Long name for region
Region_type	Type of region including continental, national,Province_State,BCR, bcr_by_national, or stratum
Strata_included	Strata included in the trend and annual index calculations
Strata_excluded	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
Trend	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
Trend_Q_quantiles	quantiles of the posterior distribution of Trend estimates, matching levels included in the quantiles argument
Percent_Change	Estimated total percent change over the trend time-period
Percent_Change_Q_quantiles	quantiles of the posterior distribution of Percent Change estimates, matching levels included in the quantiles argument
Slope_Trend	Estimated mean annual percent change over the trend time-period, according to the slope of a linear regression through the log-transformed annual indices
Slope_Trend_Q_quantiles	quantiles of the posterior distribution of Percent Change estimates, matching levels included in the quantiles argument
prob_decrease_X_percent	proportion of the posterior distribution of Percent_Change that is below the percentage values supplied in prob_decrease
prob_increase_X_percent	proportion of the posterior distribution of Percent_Change that is above the percentage values supplied in prob_increase
Relative_Abundance	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
Observed_Relative_Abundance	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
Number_of_Strata	The number of strata included in the region
Width_of_X_percent_Credible_Interval	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_of_X_percent_Credible_Interval_Slope	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)
Number_of_Routes	The number of unique BBS routes included in the trend calculation for this region and species
Mean_Number_of_Routes	The average number of BBS routes across years contributing data for this region and species
backcast_flag	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:

data_summary	dataframe with the following columns
Year	Year of particular index
Region	Region name
Index	Strata-weighted count index
additional columns for each of the values in quantiles	quantiles of the posterior distribution
samples	array of all samples from the posterior distribution
area-weights	data frame of the strata names and area weights used to calculate the continental estimates
y_min	first year used in the model, scale 1:length of time-series
y_max	last year used in the model, scale 1:length of time-series
startyear	first year used in the model, scale 1966:2018

Data frame of 2 variables:

Stratum	Name of the stratum
Trend	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:

model	The model to be used in JAGS
heavy_tailed	Logical indicating whether the extra-Poisson error distribution should be modeled as a t-distribution
min_nu	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
ncounts	The number of counts containing useful data for the species
nstrata	The number of strata used in the analysis
ymin	Minimum year used
ymax	Maximum year used
nonzeroweight	Proportion of routes in each strata with species obervation
count	Vector of counts for the species
strat	Vector of strata to be used in the analysis
obser	Vector of unique observer-route pairings
year	Vector of years for each count
firstyr	Vector of indicator variables as to whether an observer was a first year
month	vector of numeric month of observation
day	vector of numeric day of observation
nobservers	Total number of observer-route pairings
fixedyear	Median of all years (ymin:ymax), included only with slope model
nknots	Number of knots to use for smooting functions, included only with GAM
X.basis	Basis function for n smoothing functions, included only with GAM

Double precision numerical value

generate_cont_indices

For generate_cont_indices(), use generate_indices(regions = "continental").

generate_cont_trend

For generate_cont_trend(), use generate_trends().

generate_regional_indices

For generate_regional_indices(), use generate_indices().

generate_regional_trends

For generate_regional_trends(), use generate_trends().

generate_strata_indices

For generate_strata_indices(), use generate_indices(regions = "stratum").

generate_strata_trends

For generate_strata_trends(), use generate_trends().

p_waic

WAIC should no longer be used for BBS data. Cross validation should be used instead.

plot_cont_indices

For plot_cont_indices(), use plot_indices().

prepare_jags_data

For prepare_jags_data(), use prepare_data(sampler = "jags", ...).

waic

WAIC should no longer be used for BBS data. Cross validation should be used instead.

See Also

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

Examples

# 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)

BrandonEdwards/bbsBayes documentation built on Aug. 11, 2024, 9:33 a.m.