Run drjacoby MCMC — run_mcmc • drjacoby

Run MCMC either with or without parallel tempering turned on. Minimum inputs include a data object, a data.frame of parameters, a log-likelihood function and a log-prior function. Produces an object of class drjacoby_output, which contains all MCMC output along with some diagnostics and a record of inputs.

run_mcmc(
  data,
  df_params,
  misc = list(),
  loglike,
  logprior,
  burnin = 1000,
  samples = 10000,
  rungs = 1,
  chains = 5,
  beta_manual = NULL,
  alpha = 1,
  target_acceptance = 0.44,
  cluster = NULL,
  coupling_on = TRUE,
  pb_markdown = FALSE,
  save_data = TRUE,
  save_hot_draws = FALSE,
  silent = FALSE
)

Arguments

data: a named list or data frame or data values.
df_params: a data.frame of parameters (see ?define_params).
misc: optional list object passed to likelihood and prior. This can be useful for passing values that are not strictly data, for example passing a lookup table to the prior function.
loglike, logprior: the log-likelihood and log-prior functions used in the MCMC. Can either be passed in as R functions (not in quotes), or as character strings naming compiled C++ functions (in quotes).
burnin: the number of burn-in iterations. Automatic tuning of proposal standard deviations is only active during the burn-in period.
samples: the number of sampling iterations.
rungs: the number of temperature rungs used in the parallel tempering method. By default, \(\beta\) values are equally spaced between 0 and 1, i.e. \(\beta[i]=\)(i-1)/(rungs-1) for i in 1:rungs. The likelihood for the i^th heated chain is raised to the power \(\beta[i]^\alpha\), meaning we can use the \(\alpha\) parameter to concentrate rungs towards the start or the end of the interval (see the alpha argument).
chains: the number of independent replicates of the MCMC to run. If a cluster object is defined then these chains are run in parallel, otherwise they are run in serial.
beta_manual: vector of manually defined \(\beta\) values used in the parallel tempering approach. If defined, this overrides the spacing defined by rungs. Note that even manually defined \(\beta\) values are raised to the power \(\alpha\) internally, hence you should set alpha = 1 if you want to fix \(\beta\) values exactly.
alpha: the likelihood for the i^th heated chain is raised to the power \(\beta[i]^\alpha\), meaning we can use the \(\alpha\) parameter to concentrate rungs towards the start or the end of the temperature scale.
target_acceptance: Target acceptance rate. Should be between 0 and 1. Default of 0.44, set as optimum for unvariate proposal distributions.
cluster: option to pass in a cluster environment, allowing chains to be run in parallel (see package "parallel").
coupling_on: whether to implement Metropolis-coupling over temperature rungs. The option of deactivating coupling has been retained for general interest and debugging purposes only. If this parameter is FALSE then parallel tempering will have no impact on MCMC mixing.
pb_markdown: whether to run progress bars in markdown mode, meaning they are only updated when they reach 100% to avoid large amounts of output being printed to markdown files.
save_data: if TRUE (the default) the raw input data is stored for reference in the project output. This allows complete reproducibility from a project, but may be undesirable when datasets are very large.
save_hot_draws: if TRUE the parameter draws relating to the hot chains are also stored inside the pt element of the project output. If FALSE (the default) only log-likelihoods and log-priors are stored from heated chains.
silent: whether to suppress all console output.

Details

Note that both data and misc are passed into log-likelihood/log-prior functions *by reference*. This means if you modify these objects inside the functions then any changes will persist.