From 8cc85efe132c1d06518c3c10b1b7788a0d1c6108 Mon Sep 17 00:00:00 2001 From: Joe Thorley Date: Mon, 29 Apr 2024 21:23:18 -0700 Subject: [PATCH 01/10] update description in DESCRIPTION --- DESCRIPTION | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/DESCRIPTION b/DESCRIPTION index 31e3e8d..c3b72e7 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -12,7 +12,8 @@ Authors@R: c( person("Environment and Climate Change Canada", role = "cph") ) Description: Estimates annual survival, recruitment and population growth - for boreal caribou populations using hierarchical Bayesian models. + for boreal caribou populations using Bayesian and Maximum Likelihood + models with fixed and random effects. License: Apache License (== 2.0) | file LICENSE URL: https://poissonconsulting.github.io/bboutools/ BugReports: https://github.com/poissonconsulting/bboutools/issues From 123a7a96fb7e097abd850dc4a1bc5e44ed2b92a8 Mon Sep 17 00:00:00 2001 From: Joe Thorley Date: Mon, 29 Apr 2024 21:24:52 -0700 Subject: [PATCH 02/10] add url to code --- DESCRIPTION | 2 +- man/bboutools-package.Rd | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index c3b72e7..6a060d9 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -15,7 +15,7 @@ Description: Estimates annual survival, recruitment and population growth for boreal caribou populations using Bayesian and Maximum Likelihood models with fixed and random effects. License: Apache License (== 2.0) | file LICENSE -URL: https://poissonconsulting.github.io/bboutools/ +URL: https://github.com/poissonconsulting/bboutools, https://poissonconsulting.github.io/bboutools/ BugReports: https://github.com/poissonconsulting/bboutools/issues Depends: nimble, diff --git a/man/bboutools-package.Rd b/man/bboutools-package.Rd index f6410b3..bdda759 100644 --- a/man/bboutools-package.Rd +++ b/man/bboutools-package.Rd @@ -6,11 +6,12 @@ \alias{bboutools-package} \title{bboutools: Boreal Caribou Survival, Recruitment and Population Growth} \description{ -Estimates annual survival, recruitment and population growth for boreal caribou populations using hierarchical Bayesian models. +Estimates annual survival, recruitment and population growth for boreal caribou populations using Bayesian and Maximum Likelihood models with fixed and random effects. } \seealso{ Useful links: \itemize{ + \item \url{https://github.com/poissonconsulting/bboutools} \item \url{https://poissonconsulting.github.io/bboutools/} \item Report bugs at \url{https://github.com/poissonconsulting/bboutools/issues} } From cb279e48a574cfe08b811714e8e9b26ebdd93b25 Mon Sep 17 00:00:00 2001 From: Joe Thorley Date: Mon, 29 Apr 2024 21:25:31 -0700 Subject: [PATCH 03/10] tidy description --- DESCRIPTION | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/DESCRIPTION b/DESCRIPTION index 6a060d9..ce85d98 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -15,7 +15,8 @@ Description: Estimates annual survival, recruitment and population growth for boreal caribou populations using Bayesian and Maximum Likelihood models with fixed and random effects. License: Apache License (== 2.0) | file LICENSE -URL: https://github.com/poissonconsulting/bboutools, https://poissonconsulting.github.io/bboutools/ +URL: https://github.com/poissonconsulting/bboutools, + https://poissonconsulting.github.io/bboutools/ BugReports: https://github.com/poissonconsulting/bboutools/issues Depends: nimble, From 6df89426cd44325c46d810846aef5175f4bea3ee Mon Sep 17 00:00:00 2001 From: Joe Thorley Date: Tue, 30 Apr 2024 03:29:50 -0700 Subject: [PATCH 04/10] use remotes for install as itself is quick and easy to install --- README.Rmd | 4 ++-- README.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/README.Rmd b/README.Rmd index aaac4bc..cb8dc1f 100644 --- a/README.Rmd +++ b/README.Rmd @@ -30,8 +30,8 @@ library(bboutools) To install the latest development version: ``` r -# install.packages("pak") -pak::pak("poissonconsulting/bboutools") +# install.packages("remotes") +remotes::install_github("poissonconsulting/bboutools") ``` ## Introduction diff --git a/README.md b/README.md index 90ed11b..aaa64bb 100644 --- a/README.md +++ b/README.md @@ -21,8 +21,8 @@ facilitate direct comparison of estimates across jurisdictions. To install the latest development version: ``` r -# install.packages("pak") -pak::pak("poissonconsulting/bboutools") +# install.packages("remotes") +remotes::install_github("poissonconsulting/bboutools") ``` ## Introduction From d537003e00516ffc6d83b7c47b735ac0532b0f4e Mon Sep 17 00:00:00 2001 From: Joe Thorley Date: Tue, 30 Apr 2024 03:34:44 -0700 Subject: [PATCH 05/10] bit more on models in readme --- README.Rmd | 3 ++- README.md | 6 ++++-- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/README.Rmd b/README.Rmd index cb8dc1f..493266f 100644 --- a/README.Rmd +++ b/README.Rmd @@ -23,7 +23,8 @@ library(bboutools) [![Codecov test coverage](https://codecov.io/gh/poissonconsulting/bboutools/branch/main/graph/badge.svg)](https://app.codecov.io/gh/poissonconsulting/bboutools?branch=main) -`bboutools` is an R package to estimate the annual survival, recruitment and population growth for boreal caribou using Bayesian models to facilitate direct comparison of estimates across jurisdictions. +`bboutools` is an R package to estimate the annual survival, recruitment and population growth for boreal caribou populations using Bayesian and Maximum Likelihood models with fixed and random effects. +It was developed to facilitate direct comparison of estimates across jurisdictions. ## Installation diff --git a/README.md b/README.md index aaa64bb..9589cfb 100644 --- a/README.md +++ b/README.md @@ -13,8 +13,10 @@ coverage](https://codecov.io/gh/poissonconsulting/bboutools/branch/main/graph/ba `bboutools` is an R package to estimate the annual survival, recruitment -and population growth for boreal caribou using Bayesian models to -facilitate direct comparison of estimates across jurisdictions. +and population growth for boreal caribou populations using Bayesian and +Maximum Likelihood models with fixed and random effects. It was +developed to facilitate direct comparison of estimates across +jurisdictions. ## Installation From 9bd31007d3baacaab344f0555d8f31a3a9e9a357 Mon Sep 17 00:00:00 2001 From: Joe Thorley Date: Tue, 30 Apr 2024 03:43:09 -0700 Subject: [PATCH 06/10] minor edits to vignette --- vignettes/bboutools.Rmd | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/vignettes/bboutools.Rmd b/vignettes/bboutools.Rmd index ae1378e..89b2d0e 100644 --- a/vignettes/bboutools.Rmd +++ b/vignettes/bboutools.Rmd @@ -41,8 +41,8 @@ In order to install R [@r] the appropriate binary for the users operating system Once R is installed, the `bboutools` package can be installed from GitHub by executing the following code at the R console ```{r, eval=FALSE} -install.packages("pak") -pak::pak("poissonconsulting/bboutools") +install.packages("remotes") +remotes::install_github("poissonconsulting/bboutools") ``` The `bboutools` package can then be loaded into the current session using @@ -62,7 +62,8 @@ If you discover a bug in `bboutools` please file an issue with a [reprex](https: ## Providing Data Once the `bboutools` package has been loaded, the next task is to provide some data. -An easy way to do this is to create a comma separated file (`.csv`) with spreadsheet software. Recruitment and survival data should be formatted as in the following anonymized datasets and can be checked to confirm it is in the correct format by using the `bboudata` functions: +An easy way to do this is to create a comma separated file (`.csv`) with spreadsheet software. +Recruitment and survival data should be formatted as in the following anonymized datasets and can be checked to confirm it is in the correct format by using the `bboudata` functions: ```{r} # Recruitment data @@ -107,7 +108,8 @@ If `adult_female_proportion = NULL`, the adult female proportion is estimated fr By default, a biologically informative prior of `Beta(65,35)` is used. This corresponds to an expected value of 65%. -The yearling female proportion can be set with `yearling_female_proportion`. The default value is 0.5. +The yearling female proportion can be set with `yearling_female_proportion`. +The default value is 0.5. The model can be fit with random effect of year, fixed effect of year and/or continuous effect of year (i.e., year trend). The `min_random_year` argument dictates the minimum number of years in the dataset required to fit a random year effect; otherwise a fixed year effect is fit. @@ -132,12 +134,14 @@ glance(recruitment) Model convergence provides an indication of whether the parameter estimates are reliable. -Convergence is successful if `ess` > 33% of the number of iterations and `rhat` < 1.1. +Convergence is considered successful if `ess` > 33% of the number of iterations and `rhat` < 1.1. `ess` (Effective Sample Size) represents the length of a chain (i.e., number of iterations) if each sample was independent of the one before it. `rhat` evaluates whether the chains agree on the same values. As the total variance of all the chains shrinks to the average variance within chains, r-hat approaches 1. -By default, the `bboutools` Bayesian method saves 1,000 MCMC samples from each of three chains (after discarding the first halves). The number of samples saved can be adjusted with the `niters` argument. With `niters` set, the user can simply increment the thinning rate as required to achieve convergence (i.e., by increasing `ess` and/or decreasing `rhat`). +By default, the `bboutools` Bayesian method saves 1,000 MCMC samples from each of three chains (after discarding the first halves). +The number of samples saved can be adjusted with the `niters` argument. +With `niters` set, the user can simply increment the thinning rate as required to achieve convergence (i.e., by increasing `ess` and/or decreasing `rhat`). ### Summary Various generic functions in `bboutools` can be used to summarize or interrogate the output of model fitting functions. @@ -157,7 +161,8 @@ Keep in mind that any reference to 'Year' or 'Annual' in these summary outputs r ### Priors In general, weakly informative priors are used by default [@gelman_prior_2017; @mcelreath_statistical_2016]. -The default prior distribution parameter values can be accessed from `bb_priors_recruitment()` and `bb_priors_survival()`. See the priors vignette for more information. +The default prior distribution parameter values can be accessed from `bb_priors_recruitment()` and `bb_priors_survival()`. +See the priors vignette for more information. ```{r} bb_priors_recruitment() @@ -170,7 +175,7 @@ For example, less informative priors for `adult_female_proportion` (e.g., `Beta( recruitment <- bb_fit_recruitment(bboudata::bbourecruit_a, priors = c(adult_female_proportion_alpha = 1, adult_female_proportion_beta = 1, b0_mu = 0, b0_sd = 5)) ``` -If the user is interested in fitting models without priors, see `bb_fit_recruitment_ml()`/`bb_fit_survival_ml()`, which use a Maximum Likelihood approach (see more details below). +If the user is interested in fitting models without any prior information, see `bb_fit_recruitment_ml()` and `bb_fit_survival_ml()`, which use a Maximum Likelihood approach (see more details below). ## Survival The annual survival in boreal caribou population is typically estimated from the monthly fates of collared adult females. @@ -199,7 +204,8 @@ tidy(survival, include_random_effects = FALSE) ## Predictions A user can generate and plot predictions of recruitment, survival and population growth. -Recruitment is the adjusted recruitment using methods from [@decesare_estimating_2012]. See the 'analytical methods' vignette for details. +Recruitment is the adjusted recruitment using methods from [@decesare_estimating_2012]. +See the 'analytical methods' article for details. Predictions of calf-cow ratio can also be made using `bb_predict_calf_cow_ratio()`. @@ -258,6 +264,7 @@ bb_plot_year_population_change(predict_change) ``` ## Maximum Likelihood + Maximum Likelihood (ML) models can be fit using the `bb_fit_recruitment_ml()` and `bb_fit_survival_ml()` functions. These functions take a few seconds to execute because Nimble must compile the model into C++ code. See the [Nimble documentation](https://r-nimble.org/html_manual/cha-AD.html#how-to-use-laplace-approximation) for more information and comparison to TMB. From 3d21909897e092bb28ace7a47dee1c458fe84bb7 Mon Sep 17 00:00:00 2001 From: Joe Thorley Date: Tue, 30 Apr 2024 03:53:06 -0700 Subject: [PATCH 07/10] tweaksto priors article --- vignettes/articles/priors.Rmd | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/vignettes/articles/priors.Rmd b/vignettes/articles/priors.Rmd index 0932205..40aab3e 100644 --- a/vignettes/articles/priors.Rmd +++ b/vignettes/articles/priors.Rmd @@ -11,17 +11,17 @@ knitr::opts_chunk$set( ) ``` -A prior distribution represents our prior understanding or belief in the value of an unknown parameter. +A prior distribution represents the existing uncertainty in the value of an unknown parameter. The influence of a prior on the posterior distribution will decrease as the number of observations increases. -In general, `bboutools` uses biologically reasonable, weakly informative priors by default [@gelman_prior_2017; @mcelreath_statistical_2016]. +`bboutools` uses weakly informative priors by default [@gelman_prior_2017; @mcelreath_statistical_2016]. -If the user is interested in fitting models without priors, see `bb_fit_recruitment_ml()`/`bb_fit_survival_ml()`, which have identical models but use a frequentist approach (Maximum Likelihood) to parameter estimation. +If the user is interested in fitting models without priors, see `bb_fit_recruitment_ml()` and `bb_fit_survival_ml()`, which have identical models but use a frequentist approach (Maximum Likelihood) to parameter estimation. Models fit with Maximum Likelihood are equivalent to Bayesian models with completely uninformative priors [@mcelreath_statistical_2016]. ### Survival Given the full model, the expected survival probability for the $i^{th}$ year and $j^{th}$ month is -$$logit(Survival[i,j]) = b0 + bAnnual[i] + bMonth[j] + bYear \cdot Year[i]$$ +$$\text{logit}(Survival[i,j]) = b0 + bAnnual[i] + bMonth[j] + bYear \cdot Year[i]$$ Where $bAnnual$ can be a fixed or random effect of categorical year on the intercept on the log-odds scale and $Year$ is the scaled continuous year. This model has the following default priors in `bboutools` @@ -194,6 +194,7 @@ ggplot(data = df) + ``` -As with the above example, the adult female proportion estimate for a Bayesian model with vague priors closely matches the Maximum Likelihood estimate, whereas the Bayesian model with informative prior pulls the estimate toward the prior belief. +As with the above example, the adult female proportion estimate for a Bayesian model with vague priors closely matches the Maximum Likelihood estimate, whereas the Bayesian model with informative prior gives less weight to the data. -The $adult\_female\_proportion$ can also simply be fixed. See `bb_fit_recruitment()` for details. +The $adult\_female\_proportion$ can also simply be fixed. +See `bb_fit_recruitment()` for details. From e88622e531a6594c4c9df3814d67c59974dc11bb Mon Sep 17 00:00:00 2001 From: Joe Thorley Date: Tue, 30 Apr 2024 03:57:26 -0700 Subject: [PATCH 08/10] drop reference to laplace approximation as may be bayesian --- vignettes/articles/methods.Rmd | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/vignettes/articles/methods.Rmd b/vignettes/articles/methods.Rmd index 9eb8df2..877c414 100644 --- a/vignettes/articles/methods.Rmd +++ b/vignettes/articles/methods.Rmd @@ -33,7 +33,7 @@ The use of random effects is especially beneficial when some months/years have s In the case of sparse data or extreme values, estimates will tend to be pulled toward the mean (i.e., 'shrinkage'). For missing data, the estimate will be equal to the mean. Shrinkage may not be desired if extreme values are likely to represent the true value (e.g., numerous wolf attacks in one year). -In this case, a fixed effect model would yield better estimates. +In this case, a fixed effect model would yield more reliable estimates. Fixed and random effects can be used in Bayesian or frequentist models. @@ -41,7 +41,6 @@ Fixed and random effects can be used in Bayesian or frequentist models. The frequentist approach simply identifies the parameter values that maximize the likelihood, i.e., have the greatest probability of having produced the data if they were true. It does this by searching parameter space for the combination of parameter values with the Maximum Likelihood. -Parameter estimates for random effects can be estimated using the Laplace approximation (i.e., with software packages [TMB](https://arxiv.org/pdf/1509.00660.pdf) or [Nimble](https://r-nimble.org/html_manual/cha-AD.html#how-to-use-laplace-approximation)). The CIs are calculated using the standard errors, assuming that the likelihood is normally distributed. This approach has the advantage of being fast. From e6135c578385bc2ecde02d9dd1360b6931876468 Mon Sep 17 00:00:00 2001 From: Joe Thorley Date: Tue, 30 Apr 2024 04:02:12 -0700 Subject: [PATCH 09/10] tweaks to methods --- vignettes/articles/methods.Rmd | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/vignettes/articles/methods.Rmd b/vignettes/articles/methods.Rmd index 877c414..68fcf86 100644 --- a/vignettes/articles/methods.Rmd +++ b/vignettes/articles/methods.Rmd @@ -44,9 +44,9 @@ It does this by searching parameter space for the combination of parameter value The CIs are calculated using the standard errors, assuming that the likelihood is normally distributed. This approach has the advantage of being fast. -The Bayesian approach multiplies the likelihood by the probability of the parameter values being true based on prior knowledge to get the posterior probability of the parameter values being true based on the data. +The Bayesian approach multiplies the likelihood by the prior probability of the parameter values being true to get the posterior probability of the parameter values being true based on the data. Bayesian methods repeatedly sample from the posterior probability distributions using MCMC (Monte Carlo Markov Chain) methods. -This approach has the advantage of allowing derived parameters such as the population growth rate to be accurately estimated from the primary survival and recruitment parameters. +This approach has the advantage of allowing derived parameters such as the population growth rate to be easily estimated with full uncertainty from the primary survival and recruitment parameters. To demonstrate, we use an anonymized data set to compare annual survival estimates from a: @@ -137,7 +137,9 @@ This is a more straightforward task with Bayesian models. ## bboutools -`bboutools` provides the option to estimate parameter values using a Maximum Likelihood or a fully Bayesian approach. Random effects are used where appropriate by default. The Bayesian approach also uses biologically reasonable, weakly informative priors by default. +`bboutools` provides the option to estimate parameter values using a Maximum Likelihood or a fully Bayesian approach. +Random effects are used where appropriate by default. +The Bayesian approach also uses biologically reasonable, weakly informative priors by default. `bboutools` provides relatively simple general models that can be used to compare survival, recruitment and population growth estimates across jurisdictions. By default, the `bboutools` Bayesian method saves 1,000 MCMC samples from each of three chains (after discarding the first halves). @@ -212,6 +214,7 @@ for(i in 1:nAnnual) { ``` ### Predicted Survival, Recruitment and Population Growth + As ungulate populations are generally polygynous survival and recruitment are estimated with respect to the number of adult (mature) females. To estimate recruitment following @decesare_estimating_2012, the predicted annual calves per female adult is first divided by two to give the expected number of female calves per adult female (under the assumption of a 1:1 sex ratio). From ec16bcb0aaadc8b51a37feafa2b7c38933296781 Mon Sep 17 00:00:00 2001 From: Joe Thorley Date: Tue, 30 Apr 2024 04:51:22 -0700 Subject: [PATCH 10/10] added devtools helper --- R/devtools-helpers.R | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 R/devtools-helpers.R diff --git a/R/devtools-helpers.R b/R/devtools-helpers.R new file mode 100644 index 0000000..38d8204 --- /dev/null +++ b/R/devtools-helpers.R @@ -0,0 +1,19 @@ +# Copyright 2023 Province of Alberta +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +release_questions <- function() { + message( + "Have you confirmed Apache 2.0 license at the top of all code files?" + ) +}