Skip to contents

Run Bayesian model

Source: R/run-model.R
run_model.Rd

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,
  ...
)

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.

...

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.

See also

Other modelling functions: copy_model_file(), save_model_run()

Examples

s <- stratify(by = "bbs_cws", sample_data = TRUE)
#> Using 'bbs_cws' (standard) stratification
#> Using sample BBS data...
#> Using species Pacific Wren (sample data)
#> 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 1 Informational Message: The current Metropolis proposal is about to be rejected because of the following issue:
#> Chain 1 Exception: neg_binomial_2_log_lpmf: Precision parameter is 0, but must be positive finite! (in '/tmp/RtmpRVqUBP/model-1fa15f297e4d.stan', line 234, column 3 to column 40)
#> Chain 1 If this warning occurs sporadically, such as for highly constrained variable types like covariance matrices, then the sampler is fine,
#> Chain 1 but if this warning occurs often then your model may be either severely ill-conditioned or misspecified.
#> Chain 1 
#> Chain 1 Informational Message: The current Metropolis proposal is about to be rejected because of the following issue:
#> Chain 1 Exception: neg_binomial_2_log_lpmf: Precision parameter is 0, but must be positive finite! (in '/tmp/RtmpRVqUBP/model-1fa15f297e4d.stan', line 234, column 3 to column 40)
#> Chain 1 If this warning occurs sporadically, such as for highly constrained variable types like covariance matrices, then the sampler is fine,
#> Chain 1 but if this warning occurs often then your model may be either severely ill-conditioned or misspecified.
#> Chain 1 
#> Chain 1 Informational Message: The current Metropolis proposal is about to be rejected because of the following issue:
#> Chain 1 Exception: neg_binomial_2_log_lpmf: Precision parameter is 0, but must be positive finite! (in '/tmp/RtmpRVqUBP/model-1fa15f297e4d.stan', line 234, column 3 to column 40)
#> Chain 1 If this warning occurs sporadically, such as for highly constrained variable types like covariance matrices, then the sampler is fine,
#> Chain 1 but if this warning occurs often then your model may be either severely ill-conditioned or misspecified.
#> Chain 1 
#> Chain 1 Informational Message: The current Metropolis proposal is about to be rejected because of the following issue:
#> Chain 1 Exception: neg_binomial_2_log_lpmf: Log location parameter[1] is -nan, but must be finite! (in '/tmp/RtmpRVqUBP/model-1fa15f297e4d.stan', line 234, column 3 to column 40)
#> Chain 1 If this warning occurs sporadically, such as for highly constrained variable types like covariance matrices, then the sampler is fine,
#> Chain 1 but if this warning occurs often then your model may be either severely ill-conditioned or misspecified.
#> Chain 1 
#> 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 2 Informational Message: The current Metropolis proposal is about to be rejected because of the following issue:
#> Chain 2 Exception: neg_binomial_2_log_lpmf: Precision parameter is 0, but must be positive finite! (in '/tmp/RtmpRVqUBP/model-1fa15f297e4d.stan', line 234, column 3 to column 40)
#> Chain 2 If this warning occurs sporadically, such as for highly constrained variable types like covariance matrices, then the sampler is fine,
#> Chain 2 but if this warning occurs often then your model may be either severely ill-conditioned or misspecified.
#> Chain 2 
#> Chain 2 Informational Message: The current Metropolis proposal is about to be rejected because of the following issue:
#> Chain 2 Exception: neg_binomial_2_log_lpmf: Precision parameter is 0, but must be positive finite! (in '/tmp/RtmpRVqUBP/model-1fa15f297e4d.stan', line 234, column 3 to column 40)
#> Chain 2 If this warning occurs sporadically, such as for highly constrained variable types like covariance matrices, then the sampler is fine,
#> Chain 2 but if this warning occurs often then your model may be either severely ill-conditioned or misspecified.
#> Chain 2 
#> Chain 2 Informational Message: The current Metropolis proposal is about to be rejected because of the following issue:
#> Chain 2 Exception: neg_binomial_2_log_lpmf: Precision parameter is 0, but must be positive finite! (in '/tmp/RtmpRVqUBP/model-1fa15f297e4d.stan', line 234, column 3 to column 40)
#> Chain 2 If this warning occurs sporadically, such as for highly constrained variable types like covariance matrices, then the sampler is fine,
#> Chain 2 but if this warning occurs often then your model may be either severely ill-conditioned or misspecified.
#> Chain 2 
#> Chain 2 Informational Message: The current Metropolis proposal is about to be rejected because of the following issue:
#> Chain 2 Exception: neg_binomial_2_log_lpmf: Log location parameter[1] is -nan, but must be finite! (in '/tmp/RtmpRVqUBP/model-1fa15f297e4d.stan', line 234, column 3 to column 40)
#> Chain 2 If this warning occurs sporadically, such as for highly constrained variable types like covariance matrices, then the sampler is fine,
#> Chain 2 but if this warning occurs often then your model may be either severely ill-conditioned or misspecified.
#> Chain 2 
#> 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 54.8 seconds.
#> Chain 2 Iteration: 40 / 40 [100%]  (Sampling) 
#> Chain 2 finished in 62.0 seconds.
#> 
#> Both chains finished successfully.
#> Mean chain execution time: 58.4 seconds.
#> Total execution time: 62.1 seconds.
#> 
#> Warning: 2 of 40 (5.0%) transitions hit the maximum treedepth limit of 11.
#> See https://mc-stan.org/misc/warnings for details.
#> Saving model output to /home/runner/work/bbsBayes2/bbsBayes2/docs/reference/BBS_PacificWren_first_diff_hier_202312061501_STAN.rds