Generate regional trends

Generates trends for continent and strata and optionally for countries, states/provinces, or BCRs from analyses run on the stratifications that support these composite regions. Calculates the geometric mean annual changes in population size for composite regions.

Usage

generate_trends(
  indices,
  min_year = NULL,
  max_year = NULL,
  quantiles = c(0.025, 0.05, 0.25, 0.75, 0.95, 0.975),
  slope = FALSE,
  gam = FALSE,
  prob_decrease = NULL,
  prob_increase = NULL,
  hpdi = FALSE
)

Arguments

indices: List. Indices generated by generate_indices().
min_year: Numeric. Minimum year to use. Default (NULL) uses first year in data.
max_year: Numeric. Maximum year to use. Default (NULL) uses first year in data.
quantiles: Numeric vector. 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. Whether to calculate an alternative trend metric, the slope of a log-linear regression through the annual indices. Default FALSE, which estimates the trend as the geometric mean annual rate of change between min_year and max_year. This is the end-point definition of trend that only directly incorporates information from the two years, and therefore closely tracks the annual population fluctuations in those particular years. Conceptually, this metric of trend tracks the difference between the two years. If TRUE, trend represents the slope of a linear regression through the log-transformed annual indices of abundance for all years between min_year and max_year. This definition of trend is less sensitive to the particular annual fluctuations of a given min_year and max_year. Either metric may be more or less appropriate given the user's desired inference. The appropriate choice of metric may also depend on the model and the alternate_n choice made in generate_indices. For example if the fitted model was one of the "gamye" alternatives, and the alternate_n = "nsmooth", then the default slope = FALSE option will represent the end-point difference of the smooth component, which already excludes the annual fluctuations and so has similar inferential properties as the slope = TRUE option from the "first_diff" model.
gam: Logical. New in version 1.1.2. Optional trend calculation using end-point trends derived from posterior distribution of GAM-based smooths of each posterior draw of the estimated annual indices. Requires the output from generate_indices(., gam_smooth = TRUE).
prob_decrease: Numeric vector. Percent-decrease values for which to optionally calculate the posterior probabilities (see Details). Default is NULL (not calculated). Can range from 0 to 100.
prob_increase: Numeric vector. Percent-increase values for which to optionally calculate the posterior probabilities (see Details). Default is NULL (not calculated). Can range from 0 to Inf.
hpdi: Logical. Should credible intervals and limits be calculated using highest posterior density intervals instead of simple quantiles of the posterior distribution. Default is FALSE. these intervals are often a better descriptor of skewed posterior distributions, such as the predicted mean counts that the indices represent. Note hpd intervals are not stable for small percentages of the posterior distribution, and so hpdi = TRUE is ignored for quantiles values between 0.33 and 0.67 (i.e., if the quantiles value defines a limit for a centered hpd interval that would include < 33% of the posterior distribution).

Value

A list containing

trends - data frame of calculated population trends, one row for each region in the input indices
meta_data - meta data defining the analysis
meta_strata - data frame listing strata meta data
raw_data - data frame of summarized counts

trends contains the following columns:

start_year - First year of the trend
end_year - Last year of the trend
region - Region name
region_type - Type of region
strata_included - Strata potentially 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 start_year
trend - Estimated median annual percent change over the trend time-period according to end point comparison of annual indices for the start_year and the end_year
trend_q_XXX - Trend estimates by different quantiles
percent_change - Median overall estimate percent change over the trend time-period
percent_change_q_XXX - Percent change by different quantiles
slope_trend - Estimated median annual percent change over the trend time-period, according to the slope of a linear regression through the log-transformed annual indices. (Only if slope = TRUE)
slope_trend_q_XXX - Slope-based trend estimates by different quantiles. (Only if slope = TRUE)
width_of_95_percent_credible_interval - Width (in percent/year) of the credible interval on the trend calculation. Calculated for the widest credible interval requested in via quantiles. Default is 95 percent CI (i.e., trend_q_0.975 - trend_q_0.025)
width_of_95_percent_credible_interval_slope - Width (in percent/year) of the credible interval on the slope-based trend calculation. Calculated for the widest credible interval requested in via quantiles. Default is 95 percent CI (i.e., slope_trend_q_0.975 - slope_trend_q_0.025). (Only if slope = TRUE)
prob_decrease_XX_percent - Proportion of the posterior distribution of percent_change that is below the percentage values in prob_decrease (if non-Null)
prob_increase_XX_percent - Proportion of the posterior distribution of percent_change that is above tthe percentage values in prob_increase (if non-Null)
rel_abundance - Mean annual index value across all years. An estimate of the average relative abundance of the species in the region. Can be interpreted 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
obs_rel_abundance - Mean observed annual count 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.
n_routes - Number of BBS routes that contributed data for this species and region for all years in the selected time-series, i.e., all years since start_year
mean_n_routes - Mean number of BBS routes that contributed data for this species, region, and year
n_strata_included - The number of strata included in the region
backcast_flag - Approximate annual average proportion of the covered species range that is free of extrapolated population trajectories. e.g., if 1.0, data cover full time-series; if 0.75, data cover 75 percent of time-series. Only calculated if max_backcast != NULL.

Details

The posterior probabilities can be calculated for a percent-decrease (prob_decrease) and/or percent-increase (prob_increase) if desired. These calculate the probability that the population has decreased/increased by at least the amount specified.

For example, a prob_increase = 100 would result in the calculation of the probability that the population has increased by more than 100% (i.e., doubled) over the period of the trend.

Alternatively, a prob_decrease = 50 would result in the calculation of the probability that the population has decreased by more than 50% (i.e., less than half of the population remains) over the period of the trend.

Examples

# Using the example model for Pacific Wrens...

# Generate the continental and stratum indices
i <- generate_indices(pacific_wren_model)
#> Processing region continent
#> Processing region stratum

# Now, generate the trends
t <- generate_trends(i)

# Use the slope method
t <- generate_trends(i, slope = TRUE)

# Calculate probability of the population declining by 50%
t <- generate_trends(i, prob_decrease = 50)

Usage

Arguments

Value

Details

See also

Examples