Run Bayesian model

Run Bayesian model with cmdstandr::sample()using prepare data and model parameters specified in previous steps.

Usage

run_model(
  model_data,
  refresh = 100,
  chains = 4,
  parallel_chains = 4,
  iter_warmup = 1000,
  iter_sampling = 1000,
  adapt_delta = 0.8,
  max_treedepth = 11,
  k = NULL,
  output_basename = NULL,
  output_dir = ".",
  save_model = TRUE,
  overwrite = FALSE,
  retain_csv = FALSE,
  set_seed = NULL,
  quiet = FALSE,
  show_exceptions = FALSE,
  init_alternate = NULL,
  ...
)

Arguments

model_data: List. Model data generated by prepare_model().
refresh: Numeric. Passed to cmdstanr::sample(). Number of iterations between screen updates. If 0, only errors are shown.
chains: Numeric. Passed to cmdstanr::sample(). Number of Markov chains to run.
parallel_chains: Numeric. Passed to cmdstanr::sample(). Maximum number of chains to run in parallel.
iter_warmup: Numeric. Passed to cmdstanr::sample(). Number of warmup iterations per chain.
iter_sampling: Numeric. Passed to cmdstanr::sample(). Number of sampling (post-warmup) iterations per chain.
adapt_delta: Numeric. Passed to cmdstanr::sample(). The adaptation target acceptance statistic.
max_treedepth: Numeric. Passed to cmdstanr::sample(). The maximum allowed tree depth for the NUTS engine. See ?cmdstanr::sample.
k: Numeric. The K-fold group to run for cross-validation. Only relevant if folds defined by prepare_model(calculate_cv = TRUE) or custom definition. See ?prepare_model or the models article for more details.
output_basename: Character. Name of the files created as part of the Stan model run and the final model output RDS file if save_model = TRUE. Defaults to a character string that is unique to the species, model, model_variant, and system time of model_run() call (nearest minute).
output_dir: Character. Directory in which all model files will be created. Defaults to the working directory, but recommend that the user sets this to a particular existing directory for better file organization.
save_model: Logical. Whether or not to save the model output to file as an RDS object with all required data. Defaults to TRUE.
overwrite: Logical. Whether to overwrite an existing model output file when saving.
retain_csv: Logical. Whether to retain the Stan csv files after the model has finished running and the fitted object has been saved. Defaults to FALSE because csv files duplicate information saved in the model output file save object, when save_model = TRUE, and so for file organization and efficient use of memory, these are deleted by default.
set_seed: Numeric. If NULL (default) no seed is set. Otherwise an integer number to be used with withr::with_seed() internally to ensure reproducibility.
quiet: Logical. Suppress progress messages? Default FALSE.
show_exceptions: Logical. Passed to cmdstanr::sample(). Defaults to FALSE. When TRUE, prints all informational messages from Stan, for example rejection of the current proposal. Disabled by default in bbsBayes2, because of the copious informational messages during the initialization period that have no bearing on model fit. If fitting a custom model, recommend setting this to TRUE.
init_alternate: Passed to init argument in cmdstanr::sample(). Replaces the initial values in the model_data[["init_values"]] created by prepare_model. Should accept any of the acceptable approaches to setting inits argment in ?cmdstanr::sample.
...: Other arguments passed on to cmdstanr::sample().

Value

List model fit and other (meta) data.

model_fit - cmdstanr model output
model_data - list of data formatted for use in Stan modelling
meta_data - meta data defining the analysis
meta_strata - data frame listing strata meta data
raw_data - data frame of summarized counts

Details

The model is set up in prepare_model(). The run_model() function does the final (and often long-running) step of actually running the model. Here is where you can tweak how the model will be run (iterations etc.).

See the models article for more advanced examples and explanations.

Examples

s <- stratify(by = "bbs_cws", sample_data = TRUE)
#> Using 'bbs_cws' (standard) stratification
#> Using sample BBS data...
#> Using species Pacific Wren (sample data)
#> Filtering to species Pacific Wren (7221)
#> Stratifying data...
#>   Combining BCR 7 and NS and PEI...
#>   Renaming routes...
p <- prepare_data(s)
pm <- prepare_model(p, model = "first_diff", model_variant = "hier")

# Run model (quick and dirty)
m <- run_model(pm, iter_warmup = 20, iter_sampling = 20, chains = 2)
#> Running MCMC with 2 chains, at most 4 in parallel...
#> 
#> Chain 1 WARNING: There aren't enough warmup iterations to fit the 
#> Chain 1          three stages of adaptation as currently configured. 
#> Chain 1          Reducing each adaptation stage to 15%/75%/10% of 
#> Chain 1          the given number of warmup iterations: 
#> Chain 1            init_buffer = 3 
#> Chain 1            adapt_window = 15 
#> Chain 1            term_buffer = 2 
#> Chain 1 Iteration:  1 / 40 [  2%]  (Warmup) 
#> Chain 2 WARNING: There aren't enough warmup iterations to fit the 
#> Chain 2          three stages of adaptation as currently configured. 
#> Chain 2          Reducing each adaptation stage to 15%/75%/10% of 
#> Chain 2          the given number of warmup iterations: 
#> Chain 2            init_buffer = 3 
#> Chain 2            adapt_window = 15 
#> Chain 2            term_buffer = 2 
#> Chain 2 Iteration:  1 / 40 [  2%]  (Warmup) 
#> Chain 1 Iteration: 21 / 40 [ 52%]  (Sampling) 
#> Chain 2 Iteration: 21 / 40 [ 52%]  (Sampling) 
#> Chain 1 Iteration: 40 / 40 [100%]  (Sampling) 
#> Chain 1 finished in 52.8 seconds.
#> Chain 2 Iteration: 40 / 40 [100%]  (Sampling) 
#> Chain 2 finished in 55.9 seconds.
#> 
#> Both chains finished successfully.
#> Mean chain execution time: 54.4 seconds.
#> Total execution time: 56.1 seconds.
#> 
#> Saving model output to /home/runner/work/bbsBayes2/bbsBayes2/docs/reference/BBS_PacificWren_first_diff_hier_202410111703_STAN.rds

Usage

Arguments

Value

Details

See also

Examples