adnuts (version 1.0.1)

sample_admb: Bayesian inference of an ADMB model using the no-U-turn sampler.

Description

Draw Bayesian posterior samples from an AD Model Builder (ADMB) model using an MCMC algorithm. This function generates posterior samples from which inference can be made. Adaptation schemes are used so specifying tuning parameters is not necessary, and parallel execution reduces overall run time.

Usage

sample_admb(model, path = getwd(), iter = 2000, init = NULL,
  chains = 3, warmup = NULL, seeds = NULL, thin = 1,
  mceval = FALSE, duration = NULL, parallel = FALSE, cores = NULL,
  control = NULL, algorithm = "NUTS", ...)

Arguments

model

Name of model (i.e., model.tpl)

path

Path to model executable. Defaults to working directory. Often best to have model files in a separate subdirectory, particularly for parallel.

iter

The number of samples to draw.

init

A list of lists containing the initial parameter vectors, one for each chain or a function. It is strongly recommended to initialize multiple chains from dispersed points. A of NULL signifies to use the starting values present in the model (i.e., obj$par) for all chains.

chains

The number of chains to run.

warmup

The number of warmup iterations.

seeds

A vector of seeds, one for each chain.

thin

The thinning rate to apply to samples. Typically not used with NUTS.

mceval

Whether to run the model with -mceval on samples from merged chains.

duration

The number of minutes after which the model will quit running.

parallel

A boolean for whether to use parallel cores. The package snowfall is used if TRUE.

cores

The number of cores to use for parallel execution.

control

A list to control the sampler. See details for further use.

algorithm

Which algorithm to use, either "NUTS" or "RWM".

...

Further arguments to be passed to the algorithm. See help files for the samplers for further arguments.

Warning

The user is responsible for specifying the model properly (priors, starting values, desired parameters fixed, etc.), as well as assessing the convergence and validity of the resulting samples (e.g., through the coda package), or with function launch_shinytmb before making inference. Specifically, priors must be specified in the template file for each parameter. Unspecified priors will be implicitly uniform.

Details

This function implements algorithm 6 of Hoffman and Gelman (2014), and loosely follows package rstan. The step size can be adapted or specified manually. The metric (i.e., mass matrix) can be unit diagonal, adapted diagonal (default and recommended), or a dense matrix specified by the user. Further control of algorithms can be specified with the control argument. Elements are:

adapt_delta

The target acceptance rate. D

metric

The mass metric to use. Options are: "unit" for a unit diagonal matrix; NULL to estimate a diagonal matrix during warmup; a matrix to be used directly (in untransformed space).

adapt_delta

Whether adaptation of step size is turned on.

adapt_mass

Whether adaptation of mass matrix is turned on. Currently only allowed for diagonal metric.

max_treedepth

Maximum treedepth for the NUTS algorithm.

stepsize

The stepsize for the NUTS algorithm. If NULL it will be adapted during warmup.

Examples

# NOT RUN {
## This is the packaged simple regression model
path.simple <- system.file('examples', 'simple', package='adnuts')
## It is best to have your ADMB files in a separate folder and provide that
## path, so make a copy of the model folder locally.
path <- 'simple'
dir.create(path)
trash <- file.copy(from=list.files(path.simple, full.names=TRUE), to=path)
## Compile and run model
oldwd <- getwd()
setwd(path)
system('admb simple.tpl')
system('simple')
setwd('..')
init <- function() rnorm(2)
## Run NUTS with defaults
fit <- sample_admb(model='simple', init=init, path=path)
unlink(path, TRUE) # cleanup folder
setwd(oldwd)
# }
# NOT RUN {
# }