generate_trends: Generate regional trends continent and strata and optionally...

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

Generate regional trends continent and strata and optionally for countries, states/provinces, or BCRs from analyses run on the stratifications that support these composite regions

Description

generate_trends calculates the geometric mean annual changes in population size for composite regions.

Usage

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

Arguments

indices	regional indices generated by generate_indices
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
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)
slope	Logical, if TRUE, calculates an alternative trend metric, the slope of a log-linear regression through the annual indices. Default FALSE
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.

Value

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 annual indices for this region and species, i.e., number of routes for this region and species for the years since generate_indices(startyear)
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 supported by data in a given region and year, e.g., 1.0 = data cover full time-series, 0.75 = data cover 75 percent of time-series. Only calculated if max_backcast != NULL

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.
jags_data <- prepare_jags_data(strat_data = strat_data,
                               species_to_run = "Pacific Wren",
                               model = "firstdiff",
                               min_year = 2009,
                               max_year = 2018)

# Now run a JAGS model.
jags_mod <- run_model(jags_data = jags_data,
                      n_adapt = 0,
                      n_burnin = 0,
                      n_iter = 10,
                      n_thin = 1)

# Generate the continental and stratum indices
indices <- generate_indices(jags_mod = jags_mod,
                            jags_data = jags_data)

# Now, generate the trends
trends <- generate_trends(indices = indices)

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