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,
  Min_year,
  Max_year
)

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.

prob_decrease

Numeric vector. Percent-decrease values for which to optionally calculate the posterior probabilities (see Details). Default is NULL (do not calculate).

prob_increase

Numeric vector. Percent-increase values for which to optionally calculate the posterior probabilities (see Details). Default is NULL (do not calculate).

Min_year

Deprecated. Use min_year instead

Max_year

Deprecated. Use max_year instead

Value

A list containing the trends (trends), meta data for the analysis (meta_data), meta data for the strata (meta_strata) and prepared data counts from prepare_data() (raw_data).

trends is a data frame with one row for each region in the input indices. It has 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 populationhas 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 stratum
#> Processing region continent

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