Skip to contents

Generate regional trends

Source: R/generate-trends.R
generate_trends.Rd

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,
  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.

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 hdpi = 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.

See also

Other indices and trends functions: generate_indices(), plot_geofacet(), plot_indices(), plot_map()

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)