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 of numeric data values. When using C++ likelihood and/or prior these values are treated internally as doubles, so while integer and Boolean values can be used, keep in mind that these will be recast as doubles in the likelihood (i.e. `TRUE = 1.0`).
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.