update citation and vignettes

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
 

README.md

@@ -70,14 +70,15 @@ remotes::install_github("bbsBayes/bbsBayes2")
 
 If you want to install the developmental branch (which often includes additional 
 options and newest updates), you can use the following.
+NOTE: bbsBayes2 is supported by a small team of committed researchers with limited capacity. The development branch may not be stable. 
 
 ```{r}
 pak::pkg_install("bbsBayes/bbsBayes2@dev")
 ```
 
 ## Why bbsBayes2
 
-We hope you'll agree that the BBS is a [spectacular dataset](https://doi.org/10.1650/CONDOR-17-62.1). Generations of committed and expert birders have contributed their time and expertise to carefully keeping track of local bird populations. For many BBS observers, it's been a commitment that has lasted 20, 30, or even 40 years! Many federal, state, and provincial government agencies, as well as local and national conservation organizations have supported the coordination and curation of over 50-years of data.
+We hope you'll agree that the BBS is a [spectacular dataset](https://doi.org/10.1650/CONDOR-17-62.1). Generations of committed and expert birders have contributed their time and expertise to carefully keeping track of local bird populations. For many BBS observers, it's been a commitment that has lasted 20, 30, or even 40 years! Many federal, state, and provincial government agencies, as well as local and national conservation organizations have supported the coordination and curation of almost 60-years of data.
 
 [The BBS was started](https://doi.org/10.1650/CONDOR-17-83.1) at the dawn of the modern North American conservation movement, inspired by changes in bird populations noticed by biologists, naturalists, farmers, and other stewards of the natural world. A continental-scale survey of birds, carefully designed to quantify changes in populations through time, in hopes that Rachel Carson's "Silent Spring", would never come to pass.
 

inst/CITATION

@@ -18,14 +18,14 @@ citEntry(
   textVersion = "Smith, A.C., Binley, A., Daly, L., Edwards, B.P.M., Ethier, D., Frei, B., Iles, D., Meehan, T.D., and Michel, N.L., and Smith, P.A. (2023). Spatially explicit Bayesian hierarchical models for avian population status and trends. https://doi.org/10.32942/X2088D"
 )
 
-citHeader("To cite the Breeding Bird Survey data in publication, please use Ziolkowski et al. 2023")
+citHeader("To cite the Breeding Bird Survey data in publication, please use the citation for the relevant data release. This is currently the default 2024 data release")
 
 citEntry(
   entry = "misc",
-  title = "North American Breeding Bird Survey Dataset 1966 - 2022",
-  version = "2023",
+  title = "North American Breeding Bird Survey Dataset 1966 - 2023",
+  version = "2024",
   publisher = "U.S. Geological Survey, Patuxent Wildlife Research Center.",
-  author = "Ziolkowski, D.J., Lutmerding, M., English, W.B., Aponte, V.I., and Hudson, M-A.R.",
-  textVersion = "Ziolkowski, D.J., Lutmerding, M., English, W.B., Aponte, V.I., and Hudson, M-A.R., 2023, North American Breeding Bird Survey Dataset 1966 - 2022: U.S. Geological Survey data release, https://doi.org/10.5066/P9GS9K64."
+  author = "Ziolkowski, D.J., Lutmerding, M., English, W.B., and Hudson, M-A.R.",
+  textVersion = "Ziolkowski, D.J., Lutmerding, M., English, W.B., and Hudson, M-A.R., 2024, North American Breeding Bird Survey Dataset 1966 - 2023: U.S. Geological Survey data release, https://doi.org/10.5066/P136CRBV."
 )
 

vignettes/_PRECOMPILE.R

@@ -2,7 +2,7 @@
 library(knitr)
 library(readr)
 library(stringr)
-
+devtools::load_all(".")
 # Make sure to put figures in local dir in knitr chunk options
 v <- list.files("vignettes", ".orig$", full.names = TRUE, recursive = TRUE)
 

vignettes/articles/advanced.Rmd

@@ -27,7 +27,7 @@ editor_options:
 
 # Some more advanced options
 
-For most of these examples, we will be using a series of saved model outputs. These model outputs can be downloaded from this [Google Drive](https://drive.google.com/drive/folders/1EMPqmRYjcw7aQ9rPfFoGFtgI0ELHY4Ga?usp=sharing). In the example code here, we have unzipped these saved model outputs and stored the *.rds* files in a local sub-directory called *output*.
+For most of these examples, we will be using a series of saved model outputs. These model outputs can be downloaded from this [Google Drive](https://drive.google.com/drive/folders/1m45wWySCJYxh4DZGfvp_xI8fRUEsE5e1?usp=sharing). In the example code here, we have unzipped these saved model outputs and stored the *.rds* files in a local sub-directory called *output*.
 
 ## Posterior Predictive Checks
 
@@ -102,7 +102,7 @@ print(ppc_overplot)
 
 ## HPDI - Highest posterior density intervals
 
-HPDI can provide a better summary of the posterior distribution than simple quantiles of the posterior distribution. HPDI are the narrowest interval that includes a particular portion of the posterior probability. For symetrical posterior distributions HPDI are the same as the Equal Density Intervals provided by taking simple quantiles of the posterior. For skewed distributions, the HPDI is less sensitive to the long-tail of the distribution. Annual indices of abundance (i.e., the index values generated by `generate_indices()`) are retransformed predictions from a log-link model and therefore often strongly skewed. HPDI values are not provided by default, but there is a logical argument `hpdi` in both `generate_trends()` and `generate_indices()`. 
+HPDI can provide a better summary of the posterior distribution than simple quantiles of the posterior distribution. HPDI are the narrowest interval that includes a particular portion of the posterior probability. For symetrical posterior distributions HPDI are the same as the Equal Density Intervals provided by taking simple quantiles of the posterior. For skewed distributions, the HPDI is less sensitive to the long-tail of the distribution. Annual indices of abundance (i.e., the index values generated by `generate_indices()`) are retransformed predictions from a log-link model and therefore often strongly skewed. HPDI values are not provided by default, but there is a logical argument `hpdi` in both `generate_trends()` and `generate_indices()`.
 For example, in the trajectory plots below, the uncertainty bounds are more symmetrical around the dark line in the lower plot using the HPDI than they are in the upper plot using the default quantiles.
 
 
@@ -122,7 +122,7 @@ trajectories_hpdi <- plot_indices(i_hpdi)
 print(trajectories$US_NM_35 / trajectories_hpdi$US_NM_35)
 ```
 
-<img src="vignettes/articles/figures/advanced_unnamed-chunk-4-1.png" alt="Population trajectories contrasting simple quantiles and HPDI for an example stratum. The HPDI uncertainty bound is more symetrical around the mean"  />
+<img src="figures/advanced_unnamed-chunk-4-1.png" alt="Population trajectories contrasting simple quantiles and HPDI for an example stratum. The HPDI uncertainty bound is more symetrical around the mean"  />
 
 
 
@@ -217,17 +217,14 @@ Here, we'll demonstrate this feature using previously generate fitted model outp
 You can download a zip-file with a saved model output for Barn Swallow here:
 
 [An example of the output from applying the spatial gamye model to Barn
-Swallow data](https://drive.google.com/file/d/1RNbM312_isopRN7Lb-jP1-wK4UvRKkHE/view?usp=sharing).
+Swallow data](https://drive.google.com/drive/folders/1m45wWySCJYxh4DZGfvp_xI8fRUEsE5e1?usp=drive_link).
 
 Unzip the file and store it in a local directory.
 In this example we've placed it in a sub-directory of our working directory called *output*.
 
 
 ``` r
 BARS <- readRDS("output/Barn_Swallow_gamye_spatial.rds")
-#> Warning in gzfile(file, "rb"): cannot open compressed file 'output/Barn_Swallow_gamye_spatial.rds', probable reason
-#> 'No such file or directory'
-#> Error in gzfile(file, "rb"): cannot open the connection
 ```
 
 We generate annual indices of abundance using the smooth-only component of the population trajectory. Then use those to estimate long-term trends (1966 - 2021), and plot those trends on a map.
@@ -236,46 +233,44 @@ We generate annual indices of abundance using the smooth-only component of the p
 ``` r
 BARS_smooth_indices <- generate_indices(BARS,
                                         alternate_n = "n_smooth")
-#> Error: object 'BARS' not found
+#> Processing region continent
+#> Processing region stratum
 BARS_trends <- generate_trends(BARS_smooth_indices)
-#> Error: object 'BARS_smooth_indices' not found
 BARS_trend_map <- plot_map(BARS_trends)
-#> Error: object 'BARS_trends' not found
 BARS_trend_map
-#> Error: object 'BARS_trend_map' not found
 ```
 
+<img src="figures/advanced_unnamed-chunk-8-1.png" alt="Population trend map for Barn Swallow, showing strata with increasing trends in shades of blue and strata with decreasing trends in shades of red"  />
+
 Then, to visualise the uncertainty in this pattern of trend estimates, we generate two maps that each display the upper and lower credible intervals of the trends. We can interpret these maps as showing the lower-bound and the upper-bound on the rates of population change for the species. For example, we can be reasonably confident that the species' trends have not been more negative than the map on the left, and are unlikely to be more positive than the map on the right.
 
 
 ``` r
 
-BARS_trend_map_lower <- plot_map(BARS_trends, alternate_column = "trend_q_0.05") + 
+BARS_trend_map_lower <- plot_map(BARS_trends, alternate_column = "trend_q_0.05") +
   labs(title = "Lower bound on trend")
-#> Error: object 'BARS_trends' not found
-BARS_trend_map_upper <- plot_map(BARS_trends, alternate_column = "trend_q_0.95") + 
+BARS_trend_map_upper <- plot_map(BARS_trends, alternate_column = "trend_q_0.95") +
   labs(title = "Upper bound on trend")+
   theme(legend.position = "none") #removing the second legend
-#> Error: object 'BARS_trends' not found
 # combined using the patchwork package
 BARS_trend_bounds_maps <- BARS_trend_map_lower + BARS_trend_map_upper + plot_layout(guides = "collect")
-#> Error: object 'BARS_trend_map_lower' not found
 BARS_trend_bounds_maps
-#> Error: object 'BARS_trend_bounds_maps' not found
 ```
 
-Alternatively, we could visualise the width of the credible interval on the trends. Here we see that most of the trend estimates have credible intervals that are narrower than approximately 2%/year, but trends for a few strata in northern regions and the south-west are less precise. Note: Because in this case we are not displaying estimates of trends specifically, the function uses the viridis colour scale. 
+<img src="figures/advanced_unnamed-chunk-9-1.png" alt="Population trend maps for Barn Swallow, showing the lower and upper bounds on the population trends, where strata with increasing trends are shown in shades of blue and strata with decreasing trends in shades of red"  />
+
+Alternatively, we could visualise the width of the credible interval on the trends. Here we see that most of the trend estimates have credible intervals that are narrower than approximately 2%/year, but trends for a few strata in northern regions and the south-west are less precise. Note: Because in this case we are not displaying estimates of trends specifically, the function uses the viridis colour scale.
 
 
 ``` r
 
-BARS_trend_map_CI_width <- plot_map(BARS_trends, alternate_column = "width_of_95_percent_credible_interval") 
-#> Error: object 'BARS_trends' not found
+BARS_trend_map_CI_width <- plot_map(BARS_trends, alternate_column = "width_of_95_percent_credible_interval")
 
 BARS_trend_map_CI_width
-#> Error: object 'BARS_trend_map_CI_width' not found
 ```
 
+<img src="figures/advanced_unnamed-chunk-10-1.png" alt="Map of the width of the credible interval on trend estimates for Barn Swallow"  />
+
 
 ## Advanced options and customized models
 
@@ -348,7 +343,7 @@ t_map <- plot_map(t)
 print(t_map)
 ```
 
-<img src="vignettes/articles/figures/advanced_unnamed-chunk-12-1.png" alt="Map of population trends for Scissor-tailed Flycatcher from 1980-2021, using the default end-point trend estimates"  />
+<img src="figures/advanced_unnamed-chunk-12-1.png" alt="Map of population trends for Scissor-tailed Flycatcher from 1980-2021, using the default end-point trend estimates"  />
 
 ### Slope-based Trends
 
@@ -377,7 +372,7 @@ t_map_slope <- plot_map(t,
 print(t_map_slope)
 ```
 
-<img src="vignettes/articles/figures/advanced_unnamed-chunk-13-1.png" alt="Map of population trends for Scissor-tailed Flycatcher from 1980-2021, using the slope-based trend estimates"  />
+<img src="figures/advanced_unnamed-chunk-13-1.png" alt="Map of population trends for Scissor-tailed Flycatcher from 1980-2021, using the slope-based trend estimates"  />
 
 ### Percent Change and probability of change
 
@@ -459,7 +454,7 @@ trajectories <- plot_indices(i_BARS)
 print(trajectories[["North"]] / trajectories[["South"]])
 ```
 
-<img src="vignettes/articles/figures/advanced_unnamed-chunk-17-1.png" alt="Population trajectories for Barn Swallow in the northern and southern parts of their range"  />
+<img src="figures/advanced_unnamed-chunk-17-1.png" alt="Population trajectories for Barn Swallow in the northern and southern parts of their range"  />
 
 ## Exporting and modifying the Stan models
 
@@ -497,7 +492,9 @@ mod<-run_model(prep,...)
 ```
 ## Example - modifying a model to include a covariate
 
-With some experience writing Stan code, there are limitless options to modify the base bbsBayes2 models and fit them using the package functions. For example, the bbsBayes models are designed to estimate how bird populations have changed in time and space. But with modifications to include predictors on the aspects of population change, they could also serve to estimate **why** pouplations have changed. Other very simple modifications could be to change the priors on particular parameters. We have used priors on the time-series components of these models that are somewhat informative. Based on the observed temporal and spatial variation from 50-years of monitoring bird populations with the BBS and the Christmas Bird Count. But some users may want priors that are less, or more, informative. See the supplementals associated with this pre-print, [Smith et al. 2023](https://doi.org/10.32942/X2088D), for more information on these priors.
+With some experience writing Stan code, there are limitless options to modify the base bbsBayes2 models and fit them using the package functions. For example, the bbsBayes models are designed to estimate how bird populations have changed in time and space. But with modifications to include predictors on the aspects of population change, they could also serve to estimate **why** pouplations have changed. Other very simple modifications could be to change the priors on particular parameters. We have used priors on the time-series components of these models that are somewhat informative. Based on the observed temporal and spatial variation from 50-years of monitoring bird populations with the BBS and the Christmas Bird Count. But some users may want priors that are less, or more, informative. See the supplementals associated with this paper, [Smith et al. 2024](https://doi.org/10.1093/ornithapp/duad056), for more information on these priors.
+
+The details on this example are from an ongoing collaboration examining the effects of annual climate factors on the relative abundance of Black Tern, which you can explore more in this [GitHub repo](https://github.com/AdamCSmithCWS/Wetland_bird_trends_moisture).
 
 ### viewing and exporting the Stan code for the models