Regional annual indices of abundance — generate

Calculate annual indices of relative abundance by year for different regions. These indices can then be used to plot population trajectories for the species, and to estimate trends.

Usage

generate_indices(
  model_output = NULL,
  quantiles = c(0.025, 0.05, 0.25, 0.75, 0.95, 0.975),
  regions = c("stratum", "continent"),
  regions_index = NULL,
  alternate_n = "n",
  start_year = NULL,
  drop_exclude = FALSE,
  max_backcast = NULL,
  quiet = FALSE,
  jags_mod,
  jags_data,
  alt_region_names,
  startyear
)

Arguments

model_output: List. Model output generated by run_model().
quantiles: Numeric. Vector of quantiles to be sampled from the posterior distribution. Default is c(0.025, 0.05, 0.25, 0.5, 0.75, 0.95, 0.975). Note that these quantiles will be used to create confidence interval bands in plot_indices() and by quantiles in generate_trends(), so make sure you specify the ones you want to use later in this step.
regions: Character. Which region(s) to summarize and calculate indices for. Default is "continent" and "stratum". Options also include "country", "prov_state", "bcr", and "bcr_by_country". Note that some regions only apply to specific stratifications. You can also supply a custom region that exists as a column in the regions_index data frame (see examples for more details).
regions_index: Data frame. Custom regions to summarize. Data frame must include all strata in the original data in one column (strata_name), and any custom regions defined as categories in other columns.
alternate_n: Character. Indicating the name of the alternative annual index parameter in a model, Default is "n", alternatives are "n2" which involves a different way of scaling the annual indices, "n_smooth" for the gam and gamye models which show only the smooth component of the trajectory, and "n_slope" for the slope models which track only the linear slope component of the model.
start_year: Numeric. Trim the data record before calculating annual indices.
drop_exclude: Logical. Whether or not 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: Numeric. The number of years to back cast stratum-level estimates before the first year that species was observed on any route in that stratum. Default is NULL, which generates annual indices for the entire time series and ignores back-casting. CWS national estimates use a back cast of 5. Note that unless drop_exclude = TRUE, problematic years are only flagged, not omitted. See Details for more specifics.
quiet: Logical. Suppress progress messages? Default FALSE.
jags_mod: Defunct. Use model_output instead
jags_data: Defunct.
alt_region_names: Defunct. Use regions_index instead
startyear: Deprecated. Use start_year instead

Value

A list containing the indices (indices), an array of posterior draws (samples), meta data for the analysis (meta_data), meta data for the strata (meta_strata) and prepared data counts from prepare_data()

(raw_data).

indices is a data frame with the following columns:

year - Year of particular index
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
index - Strata-weighted count index (median)
index_q_XXX - Strata-weighted count index (by different quantiles)
obs_mean - Mean 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
n_routes - Number of BBS routes that contributed data for this species, region, and year
n_routes_total - 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
n_non_zero - 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., if 1.0, data cover full time-series; if 0.75, data cover 75 percent of time-series. Only calculated if max_backcast != NULL.

meta_data is a list passed from run_model(), now including start_year, the first year used in the summary.

Details

max_backcast is a way to deal with the fact that the species of interest may not appear in the data until several years after the start of the record. max_backcast specifies how many years can occur before the stratum is flagged. A max_backcast of 5 will flag any stratum without a non-zero (or non-NA) observation within the first 5 years of the data record. Note that records are only flagged unless drop_exclude = TRUE. If you find that the early data record is sparse and results in the exclusion of many strata, consider trimming the early years by specifying a start_year.

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

# Generate only country indices
i_nat <- generate_indices(pacific_wren_model, regions = "country")
#> Processing region country

# Use a custom region specification (dummy example)
library(dplyr)
#> 
#> Attaching package: ‘dplyr’
#> The following objects are masked from ‘package:stats’:
#> 
#>     filter, lag
#> The following objects are masked from ‘package:base’:
#> 
#>     intersect, setdiff, setequal, union
ri <- bbs_strata[["bbs_cws"]]
ri <- mutate(ri, my_region = if_else(prov_state %in% "ON",
                                     "Ontario", "Rest"))

# Generate indices with these custom regions
i_custom <- generate_indices(
  pacific_wren_model,
  regions = c("country", "prov_state", "my_region"),
  regions_index = ri)
#> Processing region country
#> Processing region prov_state
#> Processing region my_region