update vignette to reflect default NULL seed in mcmcoptions

R/wwinference.R

@@ -32,12 +32,18 @@
 #' example data provided by the package, but this should be specified by the
 #' user based on the date they are producing a forecast
 #' @param fit_opts The fit options, which in this case default to the
-#' MCMC parameters as defined using `get_mcmc_options()`.
+#' MCMC parameters as defined using `get_mcmc_options()`. This includes
+#' the arguments passed to [`$sample()`][cmdstanr::model-method-sample]:
+#' the number of chains, the number of warmup and sampling iterations, the
+#' maximum tree depth, the average acceptance probability, and the stan PRNG
+#' seed
 #' @param generate_initial_values Boolean indicating whether or not to specify
 #' the initialization of the sampler, default is `TRUE`, meaning that
 #' initialization lists will be generated and passed as the `init` argument
 #' to the model object [`$sample()`][cmdstanr::model-method-sample] call.
 #' function
+#' @param initial_values_seed set of integers indicating the random seed of
+#' the R sampler of the initial values, default is `NULL`
 #' @param compiled_model The pre-compiled model as defined using
 #' `compile_model()`
 #'
@@ -145,6 +151,7 @@ wwinference <- function(ww_data,
                         model_spec = get_model_spec(),
                         fit_opts = get_mcmc_options(),
                         generate_initial_values = TRUE,
+                        initial_values_seed = NULL,
                         compiled_model = compile_model()) {
   if (is.null(forecast_date)) {
     cli::cli_abort(
@@ -189,6 +196,7 @@ wwinference <- function(ww_data,
   )
 
   init_lists <- NULL
+  set.seed(initial_values_seed)
   if (generate_initial_values) {
     init_lists <- c()
     for (i in 1:fit_opts$n_chains) {
@@ -344,7 +352,7 @@ fit_model <- function(compiled_model,
 #' @param n_chains integer indicating the number of MCMC chains to run, default
 #' is `4`
 #' @param seed set of integers indicating the random seed of the stan sampler,
-#' default is `123`
+#' default is NULL
 #' @param adapt_delta float between 0 and 1 indicating the average acceptance
 #' probability, default is `0.95`
 #' @param max_treedepth integer indicating the maximum tree depth of the
@@ -360,7 +368,7 @@ get_mcmc_options <- function(
     iter_warmup = 750,
     iter_sampling = 500,
     n_chains = 4,
-    seed = 123,
+    seed = NULL,
     adapt_delta = 0.95,
     max_treedepth = 12) {
   mcmc_settings <- list(

vignettes/wwinference.Rmd

@@ -286,8 +286,12 @@ settings (see the documentation for `get_mcmc_options()`),
 however this vignette will use
 the default parameter settings which includes running 4 parallel chains with
 750 warm up iterations, 500 sampling iterations for each chain, a target average
-acceptance probability of 0.95 and a maximum tree depth of 12. The user may wish
-to adjust these as they are iterating to reduce model run-time or to achieve
+acceptance probability of 0.95 and a maximum tree depth of 12. The default is
+not to set a the seed for the random number generator for the MCMC model runs
+(which would produce stochastic results each time the model is run), but for
+reproducibility we will set the seed of the Stan PRNG to `123`in this vignette.
+The user may wish to to adjust these settings as they are iterating to reduce
+model run-time or to achieve
 better convergence on a real-world use case.
 
 We also pass our preprocessed datasets (`ww_data_to_fit` and
@@ -309,7 +313,7 @@ ww_fit <- wwinference::wwinference(
     infection_feedback_pmf = infection_feedback_pmf,
     params = params
   ),
-  fit_opts = get_mcmc_options(),
+  fit_opts = get_mcmc_options(seed = 123),
   compiled_model = model
 )
 ```