updating advanced vignette

bbsBayes · Aug 31, 2023 · 3399d86 · 3399d86
1 parent f50cef9
commit 3399d86
Show file tree

Hide file tree

Showing 17 changed files with 56 additions and 21 deletions.
diff --git a/vignettes/articles/advanced.Rmd b/vignettes/articles/advanced.Rmd
@@ -20,7 +20,6 @@ editor_options:
   library(sf)
   library(patchwork)
   library(bayesplot) #to visually check convergence
-#> Warning: package 'bayesplot' was built under R version 4.3.1
   library(tidyr)
 ```
 
@@ -96,11 +95,12 @@ ppc_overplot <- ppc_overplot +
 print(ppc_overplot)
 ```
 
-<img src="figures/advanced_unnamed-chunk-4-1.png" alt="Graphical posterior predictive check overlaying the observed proportion of integer count values and the estimated proportion of count values"  />
+<img src="figures/advanced_unnamed-chunk-5-1.png" alt="Graphical posterior predictive check overlaying the observed proportion of integer count values and the estimated proportion of count values"  />
 
 ## 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.
 
 
 ```r
@@ -119,7 +119,7 @@ trajectories_hpdi <- plot_indices(i_hpdi)
 print(trajectories$US_NM_35 / trajectories_hpdi$US_NM_35)
 ```
 
-<img src="figures/advanced_unnamed-chunk-5-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-6-1.png" alt="Population trajectories contrasting simple quantiles and HPDI for an example stratum. The HPDI uncertainty bound is more symetrical around the mean"  />
 
 
 
@@ -204,7 +204,8 @@ m<-prepare_model(prepared_data = d,
 #                  ...)
 
 ```
-## Example - mapping trend uncertainty or estimated abundance
+
+## ExAMPLE - mapping uncertainty of trends or estimated abundance
 
 A new feature in version 1.1, is the ability to use the plot_map function to map any of the numerical values provided in the output from `generate_trends()`. For example, you may be interested in understanding the spatial distribution of the upper and lower bounds of a trend estimate, in order to visualise the uncertainty in the spatial distribution of trend estimates.
 
@@ -222,7 +223,8 @@ In this example we've placed it in a sub-directory of our working directory call
 ```r
 BARS <- readRDS("output/Barn_Swallow_gamye_spatial.rds")
 ```
-Then we generate annual indices of abundance using the smooth-only component of the population trajectory, use those to estimate long-term trends (1966 - 2021), and plot those trends on a map.
+
+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.
 
 
 ```r
@@ -235,20 +237,36 @@ BARS_trend_map <- plot_map(BARS_trends)
 BARS_trend_map
 ```
 
-<img src="figures/advanced_unnamed-chunk-9-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"  />
+<img src="figures/advanced_unnamed-chunk-10-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_upper <- plot_map(BARS_trends, alternate_column = "trend_q_0.95")
+BARS_trend_map_lower <- plot_map(BARS_trends, alternate_column = "trend_q_0.05") + 
+  labs(title = "Lower bound on trend")
+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
 # combined using the patchwork package
-BARS_trend_bounds_maps <- BARS_trend_map_lower / BARS_trend_map_upper + plot_layout(guides = "collect")
+BARS_trend_bounds_maps <- BARS_trend_map_lower + BARS_trend_map_upper + plot_layout(guides = "collect")
 BARS_trend_bounds_maps
 ```
 
-<img src="figures/advanced_unnamed-chunk-10-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"  />
+<img src="figures/advanced_unnamed-chunk-11-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") 
+
+BARS_trend_map_CI_width
+```
+
+<img src="figures/advanced_unnamed-chunk-12-1.png" alt="Map of the width of the credible interval on trend estimates for Barn Swallow"  />
 
 
 ## Advanced options and customized models
@@ -322,7 +340,7 @@ t_map <- plot_map(t)
 print(t_map)
 ```
 
-<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"  />
+<img src="figures/advanced_unnamed-chunk-14-1.png" alt="Map of population trends for Scissor-tailed Flycatcher from 1980-2021, using the default end-point trend estimates"  />
 
 ### Slope-based Trends
 
@@ -351,7 +369,7 @@ t_map_slope <- plot_map(t,
 print(t_map_slope)
 ```
 
-<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"  />
+<img src="figures/advanced_unnamed-chunk-15-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
 
@@ -432,7 +450,7 @@ trajectories <- plot_indices(i_BARS)
 print(trajectories[["North"]] / trajectories[["South"]])
 ```
 
-<img src="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-19-1.png" alt="Population trajectories for Barn Swallow in the northern and southern parts of their range"  />
 
 ## Exporting and modifying the Stan models
 
@@ -896,7 +914,7 @@ dif_by_count <- ggplot(cv_dif) +
 dif_by_count
 ```
 
-<img src="figures/advanced_unnamed-chunk-30-1.png" alt="Cross validation differences"  />
+<img src="figures/advanced_unnamed-chunk-32-1.png" alt="Cross validation differences"  />
 
 
 
diff --git a/vignettes/articles/advanced.Rmd.orig b/vignettes/articles/advanced.Rmd.orig
@@ -106,7 +106,8 @@ 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.
 
 ```{r, fig.cap = "", fig.alt = "Population trajectories contrasting simple quantiles and HPDI for an example stratum. The HPDI uncertainty bound is more symetrical around the mean", fig.width = 8, fig.asp = 0.6}
 # set of indices for demonstrating HPDI
@@ -202,7 +203,8 @@ m<-prepare_model(prepared_data = d,
 #                  ...)
 
 ```
-## Example - mapping trend uncertainty or estimated abundance
+
+## ExAMPLE - mapping uncertainty of trends or estimated abundance
 
 A new feature in version 1.1, is the ability to use the plot_map function to map any of the numerical values provided in the output from `generate_trends()`. For example, you may be interested in understanding the spatial distribution of the upper and lower bounds of a trend estimate, in order to visualise the uncertainty in the spatial distribution of trend estimates.
 
@@ -219,7 +221,8 @@ In this example we've placed it in a sub-directory of our working directory call
 ```{r}
 BARS <- readRDS("output/Barn_Swallow_gamye_spatial.rds")
 ```
-Then we generate annual indices of abundance using the smooth-only component of the population trajectory, use those to estimate long-term trends (1966 - 2021), and plot those trends on a map.
+
+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.
 
 ```{r, fig.cap = "", fig.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", fig.width = 8, fig.asp = 0.8}
 BARS_smooth_indices <- generate_indices(BARS,
@@ -229,17 +232,31 @@ BARS_trend_map <- plot_map(BARS_trends)
 BARS_trend_map
 
 ```
+
 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, fig.cap = "", fig.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", fig.width = 8, fig.asp = 0.6}
 
-BARS_trend_map_lower <- plot_map(BARS_trends, alternate_column = "trend_q_0.05")
-BARS_trend_map_upper <- plot_map(BARS_trends, alternate_column = "trend_q_0.95")
+BARS_trend_map_lower <- plot_map(BARS_trends, alternate_column = "trend_q_0.05") + 
+  labs(title = "Lower bound on trend")
+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
 # combined using the patchwork package
-BARS_trend_bounds_maps <- BARS_trend_map_lower / BARS_trend_map_upper + plot_layout(guides = "collect")
+BARS_trend_bounds_maps <- BARS_trend_map_lower + BARS_trend_map_upper + plot_layout(guides = "collect")
 BARS_trend_bounds_maps
 ```
 
+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, fig.cap = "", fig.alt = "Map of the width of the credible interval on trend estimates for Barn Swallow", fig.width = 8, fig.asp = 0.8}
+
+BARS_trend_map_CI_width <- plot_map(BARS_trends, alternate_column = "width_of_95_percent_credible_interval") 
+
+BARS_trend_map_CI_width
+
+```
+
 
 ## Advanced options and customized models
 

diff --git a/vignettes/articles/figures/advanced_unnamed-chunk-10-1.png b/vignettes/articles/figures/advanced_unnamed-chunk-10-1.png
diff --git a/vignettes/articles/figures/advanced_unnamed-chunk-11-1.png b/vignettes/articles/figures/advanced_unnamed-chunk-11-1.png
diff --git a/vignettes/articles/figures/advanced_unnamed-chunk-12-1.png b/vignettes/articles/figures/advanced_unnamed-chunk-12-1.png
diff --git a/vignettes/articles/figures/advanced_unnamed-chunk-14-1.png b/vignettes/articles/figures/advanced_unnamed-chunk-14-1.png
diff --git a/vignettes/articles/figures/advanced_unnamed-chunk-15-1.png b/vignettes/articles/figures/advanced_unnamed-chunk-15-1.png
diff --git a/vignettes/articles/figures/advanced_unnamed-chunk-16-1.png b/vignettes/articles/figures/advanced_unnamed-chunk-16-1.png
diff --git a/vignettes/articles/figures/advanced_unnamed-chunk-19-1.png b/vignettes/articles/figures/advanced_unnamed-chunk-19-1.png
diff --git a/vignettes/articles/figures/advanced_unnamed-chunk-29-1.png b/vignettes/articles/figures/advanced_unnamed-chunk-29-1.png
diff --git a/vignettes/articles/figures/advanced_unnamed-chunk-3-1.png b/vignettes/articles/figures/advanced_unnamed-chunk-3-1.png
diff --git a/vignettes/articles/figures/advanced_unnamed-chunk-32-1.png b/vignettes/articles/figures/advanced_unnamed-chunk-32-1.png
diff --git a/vignettes/articles/figures/advanced_unnamed-chunk-4-1.png b/vignettes/articles/figures/advanced_unnamed-chunk-4-1.png
diff --git a/vignettes/articles/figures/advanced_unnamed-chunk-5-1.png b/vignettes/articles/figures/advanced_unnamed-chunk-5-1.png
diff --git a/vignettes/articles/figures/advanced_unnamed-chunk-6-1.png b/vignettes/articles/figures/advanced_unnamed-chunk-6-1.png
diff --git a/vignettes/articles/figures/advanced_unnamed-chunk-8-1.png b/vignettes/articles/figures/advanced_unnamed-chunk-8-1.png
diff --git a/vignettes/articles/figures/advanced_unnamed-chunk-9-1.png b/vignettes/articles/figures/advanced_unnamed-chunk-9-1.png