Update for 2024 data release

.github/workflows/R-CMD-check.yaml

@@ -33,7 +33,7 @@ jobs:
       R_KEEP_PKG_SOURCE: yes
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - uses: r-lib/actions/setup-pandoc@v2
 
@@ -67,13 +67,13 @@ jobs:
 
       - name: Cache BBS data
         id: cache-data
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         with:
           path: ${{ steps.cache-dir.outputs.CACHE_DIR  }}
           key: bbs-data-${{ secrets.BBS_DATA_VERSION }}
 
       - name: Fetch BBS data
-        run: bbsBayes2:::fetch_bbs_data_internal(quiet = FALSE)
+        run: bbsBayes2:::fetch_bbs_data_internal(force = TRUE,quiet = FALSE)
         shell: Rscript {0}
 
       - uses: r-lib/actions/check-r-package@v2

.github/workflows/pkgdown.yaml

@@ -24,7 +24,7 @@ jobs:
     env:
       GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - uses: r-lib/actions/setup-pandoc@v2
 
@@ -57,7 +57,7 @@ jobs:
 
       - name: Cache BBS data
         id: cache-data
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         with:
           path: ${{ steps.cache-dir.outputs.CACHE_DIR  }}
           key: bbs-data-${{ secrets.BBS_DATA_VERSION }}

.github/workflows/test-coverage.yaml

@@ -19,7 +19,7 @@ jobs:
       GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - uses: r-lib/actions/setup-r@v2
         with:
@@ -48,7 +48,7 @@ jobs:
 
       - name: Cache BBS data
         id: cache-data
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         with:
           path: ${{ steps.cache-dir.outputs.CACHE_DIR  }}
           key: bbs-data-${{ secrets.BBS_DATA_VERSION }}
@@ -76,7 +76,7 @@ jobs:
 
       - name: Upload test results
         if: failure()
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: coverage-test-failures
           path: ${{ runner.temp }}/package

.gitignore

@@ -17,7 +17,7 @@ temp.geofacet.pdf
 *.EX.R
 R/*abundance.R
 arch/
-
+local_temp_delete/
 inst/doc
 model_outputs
 docs

CONTRIBUTING.md

@@ -34,7 +34,7 @@ Getting ready to make your first contribution? Here are a couple of tutorials yo
 - Make your changes
   - For changes beyond minor typos, add an item to NEWS.md describing the changes and add yourself to the DESCRIPTION file as a contributor
 - Push to your GitHub account
-- Submit a pull request to home base (likely master branch, but check to make sure) at `bbsBayes/bbsBayes2`
+- Submit a pull request to home base (likely main branch, but check to make sure) at `bbsBayes/bbsBayes2`
 
 # Code formatting
 

DESCRIPTION

@@ -1,11 +1,11 @@
 Package: bbsBayes2
 Type: Package
 Title: Hierarchical Bayesian Analysis of North American BBS Data
-Version: 1.1.1
+Version: 1.1.2
 Authors@R: c(person("Brandon P.M.", "Edwards", role = c("aut", "cre"),
                      email = "brandonedwards3@cmail.carleton.ca"),
               person("Adam C.", "Smith", role = "aut",
-                      email = "adam.smith2@canada.ca"),
+                      email = "adam.smith@ec.gc.ca"),
               person("Steffi", "LaZerte", role = "aut",
                       email = "steffi@steffi.ca"))
 Imports:
@@ -48,7 +48,7 @@ Description: The North American Breeding Bird Survey (BBS) is a long-running
 License: MIT + file LICENSE
 Encoding: UTF-8
 LazyData: true
-RoxygenNote: 7.2.3
+RoxygenNote: 7.3.2
 Roxygen: list(markdown = TRUE)
 Suggests: 
     cmdstanr,

LICENSE

@@ -1,2 +1,2 @@
-YEAR: 2023
+YEAR: 2024
 COPYRIGHT HOLDER: Brandon P.M. Edwards, Adam C. Smith, Steffi LaZerte

NEWS.md

@@ -4,6 +4,20 @@ editor_options:
     wrap: sentence
 ---
 
+# bbsBayes2 1.1.2
+
+-   2024 release. Includes access to the 2024 release of the BBS database (observations from 1966 through to 2023). 
+
+1.  adds options to generate spaghetti plots of population trajectories in `plot_indices`. Spaghetti plots show a selection of posterior draws of the population trajectories as many distinct lines. These lines provide a different way to summarise the uncertainty of the population trajectories that separates the uncertainty of the trends (shape of the population trajectory) from the uncertainty in the mean abundance (vertical placement on the graphs).
+
+2.  adds options to estimate trends from any model using a gam-based smooth. The gam_smooths argument in the `generate_indices(gam_smooths = TRUE)` function creates an array of posterior draws of gam smooths through the population trajectory. These posterior draws can be used in the `generate_trends(gam = TRUE)` function to estimate trends and their uncertainties based on these smooths, for any custom range of dates. These smooth trends provide an alternative to the end-point trends that are the default in bbsBayes2. If the gam argument is set to TRUE, all of the trend and population change calculations are based on the posterior array of smooths, rather than the posterior array of annual indices. Calculating the smooths in `generate_indices` requires significantly more time and so the gam_smooths option is set to FALSE by default.
+
+3.  adds informative error messages to: a) identify challenges with interpreting the observed annual means relative to estimate trajectories for composite regions (all except `stratum`); b) identify species and time-periods where analyses may be complicated by changes in species taxonomy (see `bbsBayes2::species_notes`); and c) identify when the strata_custom optional `sf` object passed to `stratify` does not have the correct crs and strata_name column type. 
+
+4.  `prepare_data` now exports columns including latitude and longitude of each BBS route start-location in the `raw_data` component of the output list.
+
+5.  fix a number of errors and issues identified in version 1.1.1.
+
 # bbsBayes2 1.1.1
 
 1.1.1 represents a patch to correct some failing checks and tests in 1.1.0, and includes all of the functionality of the 1.1.0 release.

R/aa_common_docs.R

@@ -31,7 +31,16 @@
 #'   quantiles need to have been precalculated in `generate_indices()`.
 #' @param add_observed_means Logical. Whether to include points indicating the
 #'   observed mean counts. Default `FALSE`. Note: scale of observed means and
-#'   annual indices may not match due to imbalanced sampling among routes.
+#'   annual indices may not match due to imbalanced sampling among routes. Also,
+#'   pattern of change in observed means through time should reflect estimated
+#'   population trajectories for strata-level summaries. However, the temporal
+#'   patterns may be very different between means and annual indices for composite
+#'   regions (e.g., continental, state, province, or BCR) because the indices
+#'   for composite regions account for the variation in area weights and
+#'   variation in relative abundances among strata, and the observed mean counts
+#'   do not. For strata-level assessments, these observed means can be a useful
+#'   model assessment tool. For composite regions, their interpretation is more
+#'   complicated.
 #' @param col_viridis Logical. Should the colour-blind-friendly "viridis"
 #'   palette be used. Default `FALSE`.
 #'
@@ -48,7 +57,7 @@
 #'   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
+#'   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).

R/checks.R

@@ -20,7 +20,7 @@ check_data <- function(data) {
     n <- c(n, "model_fit", "model_data", "raw_data")
     from <- "run_model()"
   } else if(type == "indices") {
-    n <- c(n, "indices", "samples", "raw_data")
+    n <- c(n, "indices", "samples", "raw_data", "gam_smooth_samples")
     from <- "generate_indices()"
   } else if (type == "trends") {
     n <- c(n, "trends", "raw_data")
@@ -280,7 +280,7 @@ check_strata <- function(strata, custom = NULL, simple = FALSE,
 }
 
 check_release <- function(release, all = FALSE) {
-  chk <- c("2020", "2022", "2023")
+  chk <- c("2020", "2022", "2023","2024")
   if(all) chk <- c("all", chk)
   check_in(release, chk)
 }
@@ -308,14 +308,16 @@ check_regions <- function(regions, stratify_by, stratify_type,
   msg <- "Stratification does not match desired regions:\n"
 
   if(stratify_by %in% c("bcr", "latlong") &
-     any(regions %in% c("country", "prov_state"))) {
+     any(regions %in% c("country", "prov_state"))
+     & stratify_type != "custom" & is.null(regions_index)) {
     stop(msg,
          "BCRs and lat-long degree block stratifications cannot be divided ",
          "into regions with political boundaries ('country', 'prov_state').",
          call. = FALSE)
   }
 
-  if(stratify_by == "prov_state" & "bcr" %in% regions){
+  if(stratify_by == "prov_state" & "bcr" %in% regions
+     & stratify_type != "custom" & is.null(regions_index)){
     stop(msg,
          "The States and Provinces stratification",
          "cannot be divided into BCR regions.",
@@ -438,6 +440,10 @@ check_sf <- function(sf, check_poly = FALSE, col = FALSE) {
     if(col && !"strata_name" %in% names(sf)) {
       stop("`", nm, "` missing column `strata_name`", call. = FALSE)
     }
+    # Check for correct column type
+    if(col && !class(sf$strata_name) %in% c("character")) {
+      stop("`", nm, "` column `strata_name` must be class character", call. = FALSE)
+    }
 
     # Check for feature types
     if(check_poly) {

R/data.R

@@ -116,3 +116,41 @@
 #' species_forms
 
 "species_forms"
+
+#' Species notes
+#'
+#' Introduced in version 1.1.2.
+#' List of species and comments returned as warning messages if the time-span of
+#' an analysis is not appropriate: A collection of species and species-complexes
+#' where observations are not consistently recorded through time. List intended to
+#' help flag particular species where some trend analyses may be inappropriate.
+#'
+#' @format ## `species_notes`
+#' A data frame with 6 rows and 5 columns
+#'
+#' - `english` - The English name of the species
+#' - `french` - Le nom francais, de l'espece
+#' - `aou` - The unique numerical identification of the species in the BBS database
+#' - `minimum_year` - The suggested first year by which the species observations are consistent
+#' - `warning` - The text warning and explanation delivered by the prepare_data function
+#'
+#' @examples
+#' species_notes
+
+"species_notes"
+
+#' equal_area_crs
+#'
+#' Introduced in version 1.1.2.
+#' The specific coordinate reference system (crs) used for the included strata maps.
+#' North_America_Albers_Equal_Area_Conic, projection that provides good visualisation
+#' of the main areas covered by the North American Breeding Bird Survey
+#'
+#' @format ## `equal_area_crs`
+#' An object of class `crs`
+#'
+#'
+#' @examples
+#' equal_area_crs
+
+"equal_area_crs"